minecraft-vfx-automation
Create and verify local Minecraft Photon VFX through MCP-HELPER, launcher links, the Photon editor, files, and logs. Use for programmatic VFX authoring and runtime checks, not ordinary mod implementat
SKILL.mdskills/minecraft-vfx-automation/SKILL.md
GitHubMinecraft VFX automation
Use this skill to verify a local Minecraft VFX test environment and discover the safest existing programmatic control path. Keep the work in the named test instance/world and avoid changing production mod source.
Boundaries
- Follow the user's current GUI instruction. When they prohibit Computer Use or Sky, do not use those tools or substitute manual mouse/keyboard input. Prefer the user's existing HTTP, MCP, IPC, command, or file interfaces.
- Do not install automation software unless the user asks. Never use
hongshi.exewhen the user says it is an online-play tool. - Do not print launcher database contents, full Java command lines, access tokens, or account identifiers. Launcher process arguments can contain credentials.
- Treat opening an editor, a listening socket, or a newly written file as partial evidence only. Verify an observable response/state change before marking a control path passed.
- Do not send state-changing world actions until the active world, control mode, action scope, and rollback or low-impact nature are clear. Prefer read-only status first and a reversible or chat-only probe for the first write.
Workflow
- Confirm the requested instance, save, and scope. Check existing processes and logs before launching anything; distinguish a process already owned by the user from one started for this check.
- Start the requested instance with its existing launcher/deep-link mechanism. Verify the game process, selected game directory, startup log, and actual world entry separately. A launcher success or title-screen process does not prove that the target save loaded.
- Discover the Helper interface from its own local debug page/JAR metadata and bounded HTTP probes. Begin with one short-timeout
GET /api/status; then inspect the route/UI inventory. A TCP listener alone is not proof of a working API. If a request hangs, stop probing rather than tying up server workers, and inspectlatest.log/launcher_log.txtfor the startup cause. - Separate read-only methods from methods that simulate input or mutate world state. Query player, world, and screen state first. Only execute commands/actions that the user requested or that are demonstrably low impact; verify each with a response, call record, log, or before/after state.
- If the mod requires a loaded save, LAN publication, or MCP control mode, treat each as a distinct precondition. Inspect the installed HTTP dispatcher, not just the debug-page selector: this build accepts
enter_control_modeoverPOST /api/cmd. Re-check/api/statusafter changing control mode. Use the reusable request wrapper in scripts/invoke-mcp-helper.ps1; it defaults to read-only actions and gates arbitrary game commands behind an explicit switch. - Inspect the installed Photon version, client commands, project format, export path, and test-instance asset directories. Read the Photon findings in references/local-interface-notes.md before reusing version-specific paths. Do not infer that
/photon_editormeans an effect can be created or played without GUI. Do not hand-write an undocumented project file format. Treat editor preview and command acceptance as partial evidence; to pass a VFX test, create/load an isolated test effect, play it in the client, and verify playback through a permitted visual/programmatic signal plus logs or resulting assets.- If MCP-HELPER exposes
photon_create_fx,photon_update_fx,photon_inspect_fx,photon_list_fx,photon_status, andphoton_play_fx, first confirm/api/statusreports a healthy HTTP service and the expected Mod build, then read the direct MCP workflow in references/local-interface-notes.md. Use these operations for supported simple single-particle effects; poll resource reload and verify visible playback. The verifiedphoton-test10build includesphoton_create_pair_fxandphoton_inspect_pair_fxfor two independently parameterized particle emitters, plusphoton_clear_fx_cachefor client-side cache invalidation. When updating an already-played ID, stop the old runtime, update, wait for resource reload, clear the Photon cache, then replay and compare screenshots. Resource reload alone leaves Photon 1.1.17's parsed FX cache stale. See the reference for the tested sequence and both-emitter evidence. - For test17 or a later compatible build, read references/advanced-photon.md. Native
photon_emitter_templateandphoton_write_fxsupport particle/trail/beam graphs, curves, named sub effects and materials.photon_update_pair_fxpreserves unspecified fields. Managed start/status/move/stop uses client-local handles and includes observed sub emitters. Verify the configured effect, not just the API response. - For concept-image or generated-texture authoring on test18, read references/asset-workflow.md. Use the installed
scripts/photon_workflow.pyfor RGBA preparation, ordered atlases, import/material-library binding, uncached continuous capture, revisions and rollback. It consumes actual local image outputs; it does not itself generate images. OpenAI image generation remains a separate tool step when requested by the user. - Use
photon_editor_load/select/fields/set_text/state/save/closefor native editor work. The numeric setter runs LDLib validation and its real change responder; verify project readback. test17 dispatches client commands on the render thread and backs up before closing or Escape. Do not runphoton_editoragain while an editor is already open. On older builds the known wrong-thread command path can leave an uninitialized screen and crash.client_resumeonly closes a pause menu. - The existing screenshot endpoint caches images for two seconds. Wait more than two seconds between baseline, playing and stopped captures; also wait for the resource reload overlay to disappear. Particle counts and render callbacks are not visible-pixel evidence.
- If MCP-HELPER exposes
- For companion tools, distinguish launch checks (process exists, window responds, version/log evidence) from editing/operation checks. On this Windows environment, launch Java GUI applications through scripts/launch-java-desktop-app.ps1 if the Codex child context produces the observed selector/loopback failure; it starts the app in a temporary interactive-user task and checks the real descendant window. For supported headless tasks such as IDEA formatting, use scripts/run-interactive-command.ps1 to capture exit code/stdout/stderr in that same context. VisualVM needs a valid
--jdkhome; this installation'svisualvm.confnow points to IDEA's JBR 25. Read the companion-tool findings in references/local-interface-notes.md before applying these machine-specific workarounds. Do not claim the application was operated when interaction was not performed. - Report each requested item as passed, failed, partial, or blocked, with the evidence and failure cause. State what is fully programmatic, what needs GUI, what is read-only, and the smallest missing interface for future automation.
Local interface notes
For the observed MCP-HELPER Forge 1.20.1 build and Photon 1.1.17 findings, read references/local-interface-notes.md. Re-probe the installed version on every new instance; these details are version-specific.
The test17 additions and acceptance boundaries are maintained in references/advanced-photon.md; earlier test10 limitations in the historical notes describe that older build. The Skill is already installed in this directory. Its archive is a backup, not a separate installation requirement.
For a single bounded, read-only Helper health check, use scripts/probe-helper-status.ps1. It sends only one GET request and reports a timeout as a failure; it does not issue game commands or retry a stalled server. To start Axolotl and attempt direct quick-play without UI control, inspect and use scripts/launch-axolotl-quickplay.ps1; it uses a temporary interactive-user Scheduled Task because a Java loopback selector failed from the Codex child process in the observed environment. It verifies the target save with live MCP world data. By default it closes an existing Axolotl launcher process before starting the requested instance; pass -KeepLauncherOpen to preserve and reuse an already-running launcher. Review its parameters, temporary task/result file, and running process ownership before reuse.