dalamud-vfx-editor

name	dalamud-vfx-editor
description	Install, operate, and troubleshoot 0ceal0t/Dalamud-VFXEditor for user-owned Final Fantasy XIV visual-effect, animation, sound, physics, UI, texture, material, model, and shader files. Use when a user asks about `/vfxedit`, AVFX, PAP, TMB, SCD, Dalamud plugin setup, effect replacement, export handoff, beta repositories, or VFXEditor source builds. Triggers on: Dalamud VFXEditor, /vfxedit, .avfx, .pap, .tmb, .scd, FFXIV VFX mod, or VFXEditor beta.
allowed-tools	Bash Read Write Edit Glob Grep
compatibility	FFXIV with XIVLauncher/Dalamud for plugin use; .NET and Dalamud development environment for source builds
metadata	{"tags":"game-development, ffxiv, dalamud, vfx, modding, asset-editor","version":"1.0.0","source":"https://github.com/0ceal0t/Dalamud-VFXEditor"}

Dalamud VFXEditor

When to use this skill

• Install the main plugin from /xlplugins or configure the beta repository.
• Identify which FFXIV file type owns an effect, animation, timeline, sound, or material change.
• Replace and edit an effect while preserving a rollback copy.
• Inspect plugin release metadata or contribute to the C# source.

Use only on user-owned local files and authorized modding workflows. Do not use this skill to bypass service controls, distribute copyrighted game assets, or interfere with other players.

Instructions

Step 1: Pick the operating lane

1. Main plugin install — XIVLauncher → /xlplugins → VFXEditor → /vfxedit.
2. Beta plugin — add the upstream repo.json URL in /xlsettings > Experimental, enable only one of main/beta, then use /vfxbeta.
3. Asset edit — identify the owning file type, snapshot the source, edit a loaded replacement, update, test, and retain rollback evidence.
4. Source contribution — clone a pinned commit, restore/build the VFXEditor.csproj, and follow current Dalamud SDK requirements.

Step 2: Identify the owning file type

Use references/file-types-and-workflow.md. Common choices:

• .avfx — particles and glow without character motion;
• .pap — character animation;
• .tmb — timeline triggers for effects, animation, and sound;
• .scd — music and sound effects;
• .atex / .tex — effect/UI/model textures;
• .shpk / .shcd — shader packages and individual shaders;
• .mtrl / .mdl — materials and meshes.

If the user only wants to hide selected effects, route to the upstream author's EasyEyes recommendation rather than constructing a replacement.

Step 3: Snapshot before editing

python3 .agent-skills/dalamud-vfx-editor/scripts/snapshot_asset.py \
  /path/to/effect.avfx --output-dir ./vfx-backups

The script copies bytes unchanged and writes a SHA-256 manifest. Keep the original, working copy, exported replacement, and test result separate.

Step 4: Perform the smallest edit

In VFXEditor:

1. select Loaded Vfx as the new source;
2. select Vfx Being Replaced as the target;
3. change only the intended parameters;
4. press UPDATE;
5. test in a controlled local scenario;
6. revert immediately if timing, attachment, visibility, sound, or performance is wrong.

For complete skill replacement, inspect the .tmb timeline rather than forcing every change into .avfx.

Step 5: Inspect release metadata when using beta builds

python3 .agent-skills/dalamud-vfx-editor/scripts/inspect_repo_manifest.py repo.json --json

Confirm internal name, assembly version, Dalamud API level, repository URL, and download links. Main and beta builds cannot be enabled together.

Step 6: Build source only in a compatible environment

The inspected project uses Dalamud.NET.Sdk/15.0.0, locked NuGet packages, and Debug, Release, and Beta configurations. Do not promise a successful build without a compatible Dalamud development installation. Prefer:

dotnet restore VFXEditor/VFXEditor.csproj --locked-mode
dotnet build VFXEditor/VFXEditor.csproj -c Debug --no-restore

Use the current upstream files as authority because Dalamud APIs and package versions change.

Step 7: Verify and hand off

Report source hash, edited file type, target path, change summary, plugin channel, game/Dalamud versions, test scenario, observed result, and rollback path. Never package unmodified game assets into the skill or repository.

Examples

Inspect the official beta manifest

curl -fsSLO https://raw.githubusercontent.com/0ceal0t/Dalamud-VFXEditor/main/repo.json
python3 .agent-skills/dalamud-vfx-editor/scripts/inspect_repo_manifest.py repo.json

Back up a timeline before replacement

python3 .agent-skills/dalamud-vfx-editor/scripts/snapshot_asset.py action.tmb

Best practices

1. Snapshot every source asset and record hashes.
2. Change one layer or parameter group at a time.
3. Keep main and beta plugin channels mutually exclusive.
4. Test attachment, timing, visibility, sound, and frame-time impact.
5. Share patches or authored assets, not copyrighted game data.

References

• references/file-types-and-workflow.md — file ownership and edit checklist.
• references/upstream.md — installation, build metadata, revision, and license.
• Dalamud VFXEditor
• Upstream guides