<a href="#support-this-engine"><img src="docs/assets/sponsor-pass.svg" alt="Support Zhuda — fund the next frame. SOL and USDC on Solana." width="1280" /></a>

Support this engine

Help an independent developer keep building open-source game tools. Your support goes toward engine work, documentation and testing on real devices.

SOL / USDC · Network: Solana — scan the card above or copy this wallet address:

E4ZEhFCYy4b5pYXJUbMC9KjRitkypyqtZvpSRerLWHCb

View wallet on Solscan · Open QR code · About supporting Zhuda

---

Drive the waterfront.

English · 简体中文

<a href="https://zhudaandzhuer.github.io/zhuda-neon-racer/harbor-film.html"><picture><source type="image/webp" srcset="https://raw.githubusercontent.com/zhudaandzhuer/zhuda-neon-racer/main/docs/media/harbor-preview.webp?v=harbor-01" /><img src="https://raw.githubusercontent.com/zhudaandzhuer/zhuda-neon-racer/main/docs/media/harbor-preview.gif?v=harbor-01" alt="HARBOR / 01: actual High-preset WebGL rendering, S800 driving, wet-road reflections and an authored dock warehouse." width="1280" /></picture></a>

HARBOR / 01 · built with zhuda-laya-engine

Light, surface and motion in a world you can enter. Drive the S800 across the waterfront: photographed PBR surfaces, HDR lighting, soft shadows, wet-road reflections and an authored dock warehouse. Explore with momentum, steering, independently animated wheels and a chase camera.

EXPLORE THE HARBOR → · WATCH IN 4K / 60 FPS →

Keyboard and touch controls. Auto / Performance / Balanced / High settings. The film uses the actual High preset at 3840 × 2160 / 60 FPS, captured frame by frame; playback cadence is not a live-performance claim. The page also offers a lighter 1080p / 60 FPS version. Capture details.

---

zhuda-laya-engine

An agent-friendly game SDK and toolchain built on LayaAir 3.4.2.

Build 2D, 3D and Spine 4.2 projects with TypeScript, a CLI and coding agents. This fork adds dependency ordering, component registration, public SDK types, visual migration checks and an MCP server to the upstream engine. The shipped workflows run without the LayaAir IDE.

Maintained by Zhuda. Rendering and physics come from LayaAir / Layabox. This is an independent fork; donations support Zhuda's work on this repository.

Play Neon Apex · Explore 100 particle effects · Try the 3D terrain lab

More games

The separate racer and four arcade games offer keyboard/touch input, levels, a win/loss state and saved progress.

| Game | Play | | --- | --- | | NEON APEX · four racing circuits, garage and upgrades | Race | | STARFALL · space combat | Launch | | EMBERBOUND · arena survival | Enter | | COREKEEP · tower defense | Defend | | TIDEBREAK · arcade rebounds | Dive in |

Game rules, art, media and deployment live in separate consumer repositories: Neon Apex and Arcade. Racing verification covers a complete live race, progress, touch input and bounded scene resources.

Explore the engine

100 particle effects

91 2D and 9 true 3D effects: body-wrapping racing airflow, magic, explosions, weather, water and UI feedback.

Try the effects · Watch the 60 FPS film · Verification

Terrain and shaders

Editable 2D tile maps and 3D heightfields, chunk streaming, LOD 1/2/4, closed sides/undersides and camera boom collision probes. The inspector includes an explicit underground view. PBR, textured, fog, dissolve and 2D tint/atlas variants are checked in real WebGL draws; sky materials can opt out of scene fog.

Open the terrain / shader lab · Terrain and shader API · Verification scope

What the fork adds

| Area | Public tools and behavior | | --- | --- | | Module loading | TopologyResolver orders 29 runtime modules and selects the required features. The 2D light profile reduces the included library payload by about 83%. | | CLI builds | zhuda-laya-build uses esbuild and TypeScript AST scanning; it emits Web builds and ESM/CJS SDK bundles. | | Component registration | @zhudaComponent and the AST scanner register classes before prefab deserialization. | | Runtime guards | EngineGuard handles known 3.4.2 integration issues, including the Graphics.setState / Button failure. | | Typed construction | ZhudaEngine, Zhuda3D, ZhudaUI and ZhudaPrefab provide code-first construction. Public types omit IDE-only declarations. | | Agent integration | The MCP server supplies API guardrails, dependency resolution, examples, diagnostics and asset/particle validators. | | Visual migration | Asset audits compare Spine 4.2 presentation data and require explicit mappings for Unity animation/material wrappers. | | Visual state contracts | SpineVisualContract rejects incomplete fallback presentation; VisualFocusContract gives focus, empty selection and reset distinct meanings. | | Static assets and UI | .lh / .ls serialization, explicit percent:false, pixel bounds and color comparison, nine-slice checks and safe-area fixtures. | | Effects | Seeded 2D/3D particles, pooling, ribbons, flipbooks, collision events, VFX materials, timelines, anchors and quality budgets. |

3D terrain, shaders and integration

The public 3D SDK adds independent consumer builds, resource leases, PBR/custom surfaces, dynamic meshes, camera/input/query contracts, clocks, 2D tile terrain and 3D heightfields with chunk streaming, editing and LOD 1/2/4.

The engine passes 84 tests. The existing integration has 41 real WebGL checks covering atlas UVs, tint, alpha, clipping, textured/fog/dissolve variants and compiler diagnostics. Documentation, terrain/shader contracts and acceptance limits describe that scope. The independent consumer pins a specific engine commit and stores its device reports. Small-scene results do not establish full-game map or server performance.

The filmic rendering API adds native-lit procedural PBR hooks, UV-derived tangents, explicit normal-map conventions, offline GGX/SH HDR lighting, an HDR/AO/bloom/ACES/TAA camera pipeline and horizontal planar reflections. A separate HARBOR visual study checks the rendered effects and resource teardown. This is an initial quality slice, with further scene and asset work required.

Quick start

Requires Node.js 24 or newer.

git clone https://github.com/zhudaandzhuer/zhuda-laya-engine.git
cd zhuda-laya-engine
npm install
npm run verify
npm start

Open http://localhost:8890/ for the local workbench.

import { ZhudaEngine, Zhuda3D } from 'zhuda-laya-engine';

const { rootScene } = await ZhudaEngine.boot({
  width: 1280,
  height: 720,
  features: ['core', '3d'],
});
const scene = Zhuda3D.createScene3D(rootScene);
Zhuda3D.createCamera(scene, {
  position: [0, 4, 8],
  rotationEuler: [-25, 0, 0],
});
Zhuda3D.createDirectionalLight(scene);

const cube = new Laya.MeshSprite3D(
  Zhuda3D.createPrimitiveMesh('box', { width: 1.5, height: 1.5, depth: 1.5 }),
);
cube.meshRenderer.sharedMaterial = Zhuda3D.createMaterial({
  albedoColor: [0.2, 0.7, 1, 1],
  shininess: 48,
});
scene.addChild(cube);

Consumer projects must load the selected Laya runtime modules before booting the SDK. Use the compiler's dependency ordering rather than mixing engine generations. Clone this repository to work on the SDK; use a packaged build or a pinned Git commit in consumer projects.

Commands

| Command | Purpose | | --- | --- | | npm run build | Generate the demo build and SDK bundles | | npm run typecheck | Check public/runtime types and application sources | | npm run doctor | Check module order, registration and known legacy API usage | | npm test | Run Node unit and integration tests | | npm run verify | Run build, typecheck, doctor and tests | | npm run pack:tarball | Create an installable package in dist/ |

Connect a coding agent

Add the bundled MCP server to your client configuration:

{
  "mcpServers": {
    "zhuda-laya-engine": {
      "command": "node",
      "args": ["/absolute/path/to/zhuda-laya-engine/packages/mcp-server/index.mjs"]
    }
  }
}

The same tools can run directly from the terminal:

node packages/mcp-server/index.mjs --tool resolve_topology --args '{"features":["3d","spine42"]}'
node packages/mcp-server/index.mjs --tool get_golden_example --args '{"id":"boot-declarative-3d"}'

Use the guardrails and validators before generating a scene. Schema validation checks data contracts; successful rendering and shader compilation require an actual WebGL draw.

Migrate assets before gameplay

Inventory the source assets first, map their presentation requirements, validate them in isolation, then connect existing game rules.

node packages/compiler/visual-asset-audit.mjs \
  --source /absolute/path/to/unity/Assets/Game \
  --target /absolute/path/to/consumer/assets \
  --strict \
  --report /absolute/path/to/consumer/dist/visual-migration.json

node packages/compiler/visual-contract-audit.mjs \
  --project /absolute/path/to/consumer

The asset audit checks Spine animations, skins, bones, slots, constraints, atlases and textures. Unknown shader mappings are blocked rather than silently replaced. Unity .anim, .controller and .mat wrappers need explicit target contracts; the converter does not promise compatibility with arbitrary Unity code.

A consumer's visual-presentation-manifest.json describes source/target presentation, scope, runtime states, non-focused targets and restoration. Declaring visualContract in zhuda.config.json makes these requirements part of the build gate.

import { VisualFocusC