native-game
Build or revise a playable 2D or 3D game in NodeTool's built-in engine: create and edit the document, generate and install art and audio, playtest and autoplay a route, capture frames, publish, and prepare a standalone web build. Also the entry point for making a game look or feel better. For a glTF model use nodetool-3d-scene. For nodetool.games calls inside a code action use api-games.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-15
- Stars
- ★ 635
- Forks
- 91
01 前言 Front Matter
- name
- native-game
- featured
- true
- description
- Build or revise a playable 2D or 3D game in NodeTool's built-in engine: create and edit the document, generate and install art and audio, playtest and autoplay a route, capture frames, publish, and prepare a standalone web build. Also the entry point for making a game look or feel better. For a glTF model use nodetool-3d-scene. For nodetool.games calls inside a code action use api-games.
03 SKILL.md 正文
Build a native game
Create and edit a versioned built-in game document. The engine owns simulation,
rendering, and web export. The default is a playable 2D top-down room.
Use dimension: "3d" for an exploration blockout with a capsule controller,
follow camera, ramps, a moving platform, a crate and scripted interactions.
Load game-direction before the first edit of a new game, an art overhaul, or
a game that plays but feels flat. Lock its style string, layer plan, feel
parameters, and pacing sheet, then keep later edits and asset prompts
consistent with that spec. Load native-game-reference when an edit needs
script hooks, events, lighting, effects, particles, 3D rendering, the audio mix,
animation graphs, input bindings, the HUD tree or performance fields. Load
native-game-performance before building a 3D game and before reporting any
game as done. Load api-games before calling nodetool.games from a code
action.
Build and revise
create_native_game {project_id, name, dimension?}creates a playable draft and returns its full id and current immutable revision. Resource ids may be full ids or exact 12-character prefixes.get_native_game {game_id, view: "outline"}reads the compact draft outline. Useview: "entity"withentity_idfor one entity orview: "full"for the whole document.source: "revision"reads an immutable revision.edit_native_game {game_id, base_updated_at?, ops}applies ordered ops to the draft and validates the result atomically. Use thedraft_updated_atfrom a read for compare-and-swap when an edit depends on that exact state. Invalid edits return an op index and field path. A generated level can replace the whole draft withops: [{op: "set_document", document}]. The replacement preserves the stored game id and revision and supports undo.- Prove it plays.
playtest_native_game {game_id, inputs?, assertions?, capture_ticks?}runs the draft for up to 18,000 ticks, subject to the wall time budget. An input can repeat withticks.justPressedfires on the first repeated tick.autoplay_native_game {game_id, target_prefix? | win?, player_id?, seed?, max_ticks?}steers a supported 2D player and returns an executedroute, observed win tick, target contacts, and authored level stats. It needs a player with amovementbehavior, or a script player withleftandrightactions, and takes jump from ajump,spaceorupaction. A prefix selects every matching authored collider, whose IDs must be unique across scenes. Win steering targets collectibles or an authoredwinorvictorytrigger. Other scripted goals needtarget_prefix. A failed steering search or exhausted budget does not prove the game impossible. Replayrouteas playtestinputswith the same seed, and checkroute_completebefore accepting the replay. A target contact alone does not prove completion. - Assert what the replay proves. 2D playtests accept three forms, and any
other returns
Unsupported assertion:{event: "win", before_tick?}requires an engine win or a scriptedwinorvictorytrigger.{event: "<name>"}requires that emitted event.{entity_id, near: {x, y, tolerance}, at_tick?}checks a position.{no_script_errors: true}fails on the first script error. 3D playtests addregion,groundedandreplay_matches(see 3D authoring).
- Look at it.
capture_native_game_frame {game_id, ticks?, sheet?}renders up to eight frames and returns image refs (asset_id,uri), not pixels. Callview_imageon each ref you judge, as a direct tool call, before reporting visual changes or polish. Inside a code action the pixels cannot arrive.sheet: truereturns one contact sheet. Captures reportcancelled,wall_time_limited, androute_complete. An interrupted capture returns only frames rendered before interruption. - Pass the performance gate before you report the game as done, and again at
each milestone: blockout, art pass, effects pass. With a shell, run
nodetool game bench,nodetool game capture --fail-on-budgetandnodetool game perf --fail-on-budgeton a route through the busiest part of the game, asnative-game-performancedescribes. The game passes when all three exit 0. Report the measured tick p95, frame p95, draw calls and triangles. Without a shell, apply that skill's budgets and authoring rules and give the user thenodetool game perfcommand. - Generate assets (see Assets). Confirm scope before spending.
publish_native_game {game_id, base_revision}publishes the current draft only when the user asks. For an explicitdocument, pass the paireddraft_updated_atreturned byget_native_gameasbase_updated_at. On a conflict, read the draft and reconcile edits.build_native_game {game_id, revision?, target?}writes a standalone web player for an owned revision under the project workspace and returns its path, only when the user asks.target: "tauri"writes a Tauri desktop app project instead, named after the game. It compiles to installers withnpm run buildwhere Rust is installed.target: "expo"writes an Expo project for iOS and Android that plays the game offline in a WebView. It runs withnpm install && npx expo start. On a touch screen the 2D player adds a floating stick forleft/right/up/downand one button per other input action, labeled with the action name. Installed media must still exist, match its recorded digest, and use a supported format.
Build a complete document
Author a whole level in a code action with the @nodetool-ai/sandbox-game pack.
Read its signatures and an example with
nodetool.packs.docs("@nodetool-ai/sandbox-game") (the direct tool is
get_sandbox_package_docs). It exports game, entity, script,
registerAssets, fill, plank, arc, constructGame and saveGame. Asset
registration records bindings, and installation supplies the bytes.
saveGame({name, document}, {games: nodetool.games, project_id}) creates a
game and saves the generated draft in one edit. To replace an existing draft,
pass game_id and its last-read base_updated_at instead of project_id.
api-games covers constructGame and retained rebuilds. Publish separately
when requested.
list_example_games {query?} discovers shipped references.
get_example_game {slug: "kindle"} reads its outline. Use view: "entity"
with entity_id to study the controller or view: "full" for the document.
Kindle is the platformer benchmark for layered art, aligned poses, terrain
edges, feel, and pacing. install_example_game {project_id, slug} copies a
bundle and its verified media into the project. A raw example document has
package:// bindings. Install the bundle before editing it as a user game.
For a workflow-based brief, design_game writes its design and build_game {workflow_id, save?} creates or selects the native game and stages its asset
graph. The graph's generated media are candidates until installed.
Scripts during play
Edit an existing script through edit_native_game with an update_behavior
document op. Supply entity_id, index and behavior: {source} to preserve the
script limits. The editor compiles changed sources
during play and continues at the current tick with
existing script state. A compile failure keeps the previous source running and
reports the error in the Console. Only source edits apply during play. Use
Restart from tick 0 to apply other draft changes or reset script state.
Changing between a function and lifecycle-object script requires a restart.
A successful reload starts a new replay checkpoint at the current tick. Saved play states use the accepted script document. Earlier checkpoints belong to older source code and cannot be loaded into the changed session.
Assets
Generation spends provider credits, and no tool prices it in advance. Before
the first generation, state which slots, kinds, prompts and models you plan,
and get the user's go-ahead unless the request already authorized that scope.
Do not invent a dollar estimate. Reuse a prior authorization instead of asking
again. Importing an input_file and building a lut cost nothing. Report
actual spend with get_cost_summary.
Call browse_native_game_assets {game_id} before replacing or regenerating
art. It returns every bound asset with usedBy, prefabs with their instances,
scenes with the assets they use, the staged candidates under the game's
assets/ folder, and slot_requests. A slot request is the template slot's
prompt and image preparation, or the prompt recorded with the asset now bound.
Use it to regenerate in the same style. Narrow the lists with query and
kind. staleSiblings lists <slot>.frame.N and <slot>.tile.M bindings that
still point at the slot's previous bytes. Rebind them with bind_asset ops
before publishing, or the sheet's animations keep drawing the old art.
generate_game_asset {game_id, slot, kind, prompt?, input_file?, provider?, model?} generates or imports, prepares, installs, and binds an asset. kind is
image, audio (speech), music, sfx, font, model or collider.
sfx uses an explicit registered node_type and its params, or imports an
existing audio file. font imports a TrueType or OpenType input_file and has
no generation model. An input_file is an owned asset URI or current workspace
path. reference_slot generates an image from an installed slot's image, which
keeps a new asset in the locked style. install: false stages a 2D candidate
without binding it. For a slow model, pass background: true, await the
returned generation, then call generate_game_asset again with
generation_id and the same game, slot, kind, prompt, and preparation.
install_native_game_asset {game_id, slot, binding, candidate_workspace_id?}
installs a staged candidate and binds it to the draft. The staged bytes must
match binding.digest. To bind an earlier candidate, call
browse_native_game_assets {game_id, digest, slot} and pass the returned
binding and draft_updated_at. An unrecorded image or audio file gets a
binding derived from its bytes. An unrecorded collider must be restaged.
Image preparation supports alpha trim, target size and crop policy, pivot, sampling, and mirror tiling. Choose at most one of these atlas or grade modes:
| Preparation | Result |
|---|---|
sheet: {cols, rows, baseline?} |
Slices a row-major sheet, trims each pose, and aligns the feet on one output row. Returns equal-sized atlas frames and bindings named <slot>.frame.<index>. baseline is a zero-based output foot row. |
tileset: {tileWidth?, tileHeight?, edges?, highlight?, shadow?} |
Builds 16 terrain variants with baked exposed-edge treatments. Returns tiles and <slot>.tile.<mask> bindings. Mask bits are top 1, right 2, bottom 4, left 8. |
lut: {size?, brightness?, contrast?, saturation?, lift?, gain?, gamma?} |
Creates an opaque packed size² × size color cube from numeric grade settings, without a generation model. Bind it to a lut render effect. |
Use returned atlas rectangles as animator frames or tile frames. Keep the locked style string in every generated visual prompt. Review foot alignment, terrain joins, lighting, and grade in viewed captures before accepting the art pass.
Audio
Install music in an audio slot, then use update_scene {scene_id, set: {music: {assetId, volume, fadeInTicks, fadeOutTicks, streaming}}} in 2D or 3D.
assetId names the installed slot. volume ranges from 0 to 1 and each fade
ranges from 0 to 600 ticks. A scene transition overlaps the outgoing fade out
and incoming fade in.
For long tracks set streaming: {loopStartSeconds, loopEndSeconds?}. The
browser streams the asset through the music bus without decoding the whole
track. Loop start defaults to 0 seconds. Loop end must exceed loop start,
and both are bounded by 86400 seconds. Omit loop end to loop to the track's
end. Omit streaming for decoded music. Loading a snapshot positions music at
the saved logical tick within the loop. Browser audio needs a user gesture.
Use set_audio {mixer} for mixer buses and audioSource for triggered effects.
See native-game-reference § Audio mix and spatial audio for their fields.
3D authoring
Create with dimension: "3d" and optional template: "exploration".
The document uses schemaVersion: 3, engineVersion: "2", meters, Y up,
forward -Z, and quaternion rotations [x, y, z, w]. A game keeps its
dimension. Read the returned outline before editing. The 2D sandbox helpers and
sprite preparation retain their 2D contracts.
Keep controller, body, collider and interactions on a gameplay root. Put the
replaceable model on a visual child using parentId. Physics roots have unit
scale and one pose owner. character3d requires a kinematic body and a capsule.
Dynamic props use primitives or prepared convex hulls. Triangle meshes require
static bodies. Collision category and mask use 16 bits in 3D. Shared friction
and restitution belong in named physicsMaterials that colliders reference by
physicsMaterial. Each scene names one activeCameraId. The camera supports perspective or orthographic projection
and fixed or follow behavior.
generate_game_asset {game_id, slot, kind: "model", input_file, preparation?}
imports an owned GLB or glTF. Provider generation requires an explicit
registered node_type with its params. Preparation normalizes dependencies to
a closed GLB, records bounds and stable node:<index>/clip:<index>
selectors, and checks resource budgets. Import settings specify scale,
forward (-z, +z, +x, -x) and origin (preserve, ground,
centerGround). For glTF with separate files, pass dependency_files as a map
from declared buffer or image URI to an owned workspace path. Unresolved
dependencies fail preparation. kind: "collider" builds collision geometry
from a GLB or glTF, or accepts an already prepared collider JSON, and requires
preparation.shape: convexHull for a dynamic prop or triangleMesh for
static level geometry. Model and collider results are candidates. Review them,
then call install_native_game_asset with the returned binding and draft
timestamp. Reinstall after editing source model bytes. The model editor
(nodetool-3d-scene) edits model assets. Gameplay stays in the game document.
A set_prefab definition includes rootId, entities, externalAssets and
externalScenes. instantiate_prefab clones that subtree with a new
instance_id and remaps internal entity references. Each runtime instance owns
its script state, physics bodies and animation state. Bind prepared clips
through animator3d.clips. An idle/run/jump rig can replace the placeholder
visual without changing its root controller or collider.
3D script input adds analog axes, look, XYZ entity.position/velocity,
grounded, world entities and query observations. It preserves isolated JSON
state, seeded random, and previous-tick event delivery. Use characterIntent
for character motion, setKinematicPose for kinematic targets, impulse or
setVelocity for dynamic bodies, and teleport for explicit discontinuities.
For continuous acceleration, return {kind: "addForce", force: {x, y, z}},
{kind: "addTorque", torque: {x, y, z}} or
{kind: "addForceAtPoint", force: {x, y, z}, point: {x, y, z}}.
The vectors and application point use world space. These commands act on the
issuing entity's active dynamic body and accumulate for one simulation tick.
Return them each tick to keep applying a load. An offset point also produces
torque. Static, kinematic and absent bodies reject them. 2D scripts do not
support them.
setVisual changes only a nonphysical visual. spawn accepts a prefab and XYZ
position, rotation and velocity. Shared emit, hud, playAnimation,
despawn and sceneTransition commands retain their meanings. Ray and shape
queries are bounded commands with a caller-supplied queryId. Results arrive
in the next tick. Scripts receive no Three.js or Rapier objects.
3D playtests accept run-length frames with pressed, justPressed, axes,
look and ticks. Assertions take {entity_id, near: {x, y, z, tolerance}},
{entity_id, region: {min, max}} and {entity_id, grounded}, each with an
optional at_tick, plus the event and no_script_errors forms. Set
restore_at_tick with a {replay_matches: true} assertion to compare restored
continuation against the recorded route. autoplay_native_game reports 3D as
unsupported, so write the route yourself and assert the win. Capture the same
source, revision, seed and inputs to review actual WebGL2 frames and state
hashes. A failed tick invalidates the session. Reset or restore a snapshot from
before the failure.
build_native_game exports a self-contained directory for an immutable
revision. Serve it over static HTTP. Models, colliders, fonts, audio and pinned
runtime files are included. The first 3D release targets desktop web and
Electron.
Platformers
New 2D games (schema 4) support side-view physics. Older documents need schema 2 or later.
- Set scene
gravity {x, y}in world units per second squared. Kinematic bodies fall atbody2d.gravityScaletimes the gravity, which defaults to1. Give floating effectsgravityScale: 0. - A body that strikes a solid loses the velocity that pushed into it. A resting
body therefore keeps zero fall speed, and a script can add a jump to
entity.velocityY. - Mark a tilemap
solid: true, or a single tilesolid, to make its tiles static colliders. Tilemapcategoryandmaskfilter them. Faces shared by neighboring solid tiles never stop a body, so a body slides along a row of tiles without catching on the seams. - A
oneWaycollider or tile stops only a body that falls onto its top. A body passes through it from below and from the sides. - A static body with a velocity, from
patrolor a script, is a moving solid. It carries the bodies that stand on it and pushes out bodies in its way. - A patrolling kinematic body turns when a wall blocks it. Set
turnAtLedges: trueon an x-axis patrol to also turn at the edge of its ground. - Frames omit tiles far outside the camera, so a large tilemap costs little to draw.
Failures and validation
Runtime event and spawned-instance limits stop the session when exceeded. A failed tick cannot be saved or resumed. Reset the session or load a snapshot from before the failure, then reduce overlapping pairs or spawning.
Validation rejects unsupported component fields. Movement requires a kinematic
body, patrol requires a body, animation requires a sprite, and asset media kinds
must match their image or audio components. Resolve validation errors before
publishing. native-game-reference § Schema versions lists which fields each
2D schema accepts.
Scope
The runtime supports separate 2D and 3D games. Mixed dimensions, multiplayer,
terrain streaming, navigation meshes, vehicles, ragdolls, retargeting and root
motion are outside this release. A glTF model is an asset, so use
nodetool-3d-scene to edit one. Existing external-engine source files can
remain in a workspace as files, but their scripts and scenes need reconstruction in
the built-in game document to become playable.
04 同仓库更多 Skills
humanizer
Rewrite AI-sounding text so it reads like the writer without changing what it says. Use when editing or reviewing prose for AI tells: not-X-but-Y contrasts, one-line closers, staged openers, forced triads, dashes everywhere, inflated claims, sales language, stock AI words, bold labels, or filler.
nodetool
Use the NodeTool MCP server to build, validate, run, and debug visual AI workflows, and to work with assets, collections, and jobs. Use when the user mentions NodeTool or asks for a workflow graph, a node, or a media generation run on their NodeTool server.
wan-2-6-prompting
Prompt Alibaba's Wan 2.6 video — text-to-video with a global style line plus timing-bracketed shots, and image-to-video that describes only what changes over time. Covers the shot-mode switch per provider, the prompt budget, negative prompts, motion intensity wording, audio input and prompt expansion. Use whenever the model id names a Wan 2.6 video route (alibaba/wan-2.6/text-to-video, alibaba/wan-2.6/image-to-video, wan-video/wan-2.6-t2v, wan-video/wan-2.6-i2v, wan-video/wan2.6-i2v-flash) on generate_video, animate_image or a TextToVideo node. Not for Wan 2.5 or 2.7, or the Wan 2.6 image routes.
video-workflow
Build a reusable NodeTool video workflow for batches or repeated inputs. For a single finished piece, use a storyboard skill.
video-clone
Analyze a reference video and recreate its shot structure with a new product or cast in NodeTool.
video-audio-continuity
Keep sound continuous across a multi-scene piece cut from generated video — why one clip per scene hard-cuts the audio at every boundary, when to write all the scenes into a single generation instead, the sound-design vocabulary that survives a provider's copyright filter, and how to check the length, the aspect ratio and the mix of what came back. Use when a piece has more than one scene and the video model writes its own audio (Seedance 2, Veo 3, MiniMax H3, Kling 2.6 and later), or when a cut's sound drops out at the shot changes.