mcpField
N
nixie-fx-runtime

nixie-fx-runtime

github.com/azakharyDevelopment2259 installsUpdated 1d ago
Repository

About nixie-fx-runtime

NixieFX Runtime is a skill for integrating compiled NixieFX visual effects into applications using Three.js or PixiJS. It covers bundle loading, host-provided assets, frame updates, runtime diagnostics, and teardown.

Key features

  1. 01Load compiled VFX export bundles
  2. 02Integrate with Three.js or PixiJS
  3. 03Resolve assets through host providers
  4. 04Update effects once per frame
  5. 05Inspect support and missing-resource reports
  6. 06Clean up runtime resources

Use cases

  1. 01Display exported effects in a Three.js scene
  2. 02Use effects in a PixiJS 2D interface
  3. 03Check missing assets and backend support

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/azakhary/nixie-fx --skill nixie-fx-runtime

After installing, type/nixie-fx-runtimein Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

agents/
openai.yaml
references/
export-bundles.md
pixi.md
three.md

Details

From the project README

NixieFX Runtime

Integrate the generated out/vfx artifact. Do not load authoring project files directly in a game.

Workflow

  1. Identify the host renderer, its render loop, asset pipeline, camera or projection, and cleanup lifecycle.

  2. Install only the selected optional peer:

    npm install nixie-fx three
# or
npm install nixie-fx pixi.js

  3. Read export-bundles.md and load the complete compiled bundle through nixie-fx/export (loadVfxExportBundle).

  4. Read exactly one backend guide unless the task requires both:

  5. Resolve textures, material graphs, meshes, and sub-effects through injected providers owned by the host application.

  6. Create the renderer and effect instance, then update the renderer exactly once per host frame.

  7. Surface manifest support reports and runtime missing-resource statistics. Do not silently treat partial or missing behavior as complete.

  8. Destroy instances, renderer-owned objects, and provider resources when their host scope ends.

Package boundaries

Use only public entrypoints:

  • nixie-fx for backend-neutral contracts and support data.
  • nixie-fx/pixi for PixiJS integration.
  • nixie-fx/three for Three.js integration.
  • nixie-fx/materials for material graph contracts.
  • nixie-fx/export for browser-safe export schemas and loading.
  • nixie-fx/export/node only for Node filesystem export tooling.

Never deep-import nixie-fx/src/**, copy runtime source into the consumer, or import the unused renderer backend.

Other engines

The export format is engine-neutral JSON with official runtimes for Three.js and PixiJS. When a project targets another engine, do not force one of these adapters in: the shared simulation (src/engine/particles.ts in the repository) is renderer-agnostic, and the Three adapter source is compact enough to serve as a reference implementation for a port.

Runtime rules

  • Let the game own its application, scene, camera, clock, URLs, caches, and error reporting.
  • Preload asynchronous assets before spawning an effect; provider getters used during rendering must be synchronous.
  • Call renderer.update(deltaSeconds) once. Do not also call instance.update(deltaSeconds) in the same frame.
  • Treat authored paths as bundle-relative lookup keys. Map them to URLs or atlas frames in the host provider.
  • Use stable seeds when deterministic playback matters.
  • Pause or destroy inactive runtimes; hidden scenes must not keep ticking.
  • For Three.js performance work, inspect per-emitter draw counts and integrate the public ThreeVfxBatcher with the host's final transparent ordering. Read the batching section in three.md. Sharing a material alone does not merge draws; supplying a custom material currently disables the stock instanced fast path.
  • Do not claim editor parity until the real exported effect has been observed in the target renderer.

Completion checks

  • Importing the selected backend succeeds without installing the other peer.
  • The loader accepts the manifest, required effect IDs, and selected backend.
  • No manifest entry is blocked for the selected backend.
  • Textures, material graphs, meshes, and sub-effects resolve without missing-reference statistics.
  • Simulation advances once per frame and stops after teardown.
  • The effect is visually checked in the real host application.

Comments

Markdown supported