@gripforgeai/mcp 0.1.10 → 0.1.12

package/dist/gamekit-tools.js

@@ -3,6 +3,7 @@ import { z } from 'zod/v4';
 export const GAMEKIT_TOOL_NAMES = [
     'gripforge_gamekit_search',
     'gripforge_gamekit_get',
+    'gripforge_gamekit_installed',
     'gripforge_gamekit_install',
     'gripforge_gamekit_remove',
     'gripforge_gamekit_configure',
@@ -11,7 +12,13 @@ export const GAMEKIT_TOOL_NAMES = [
     'gripforge_gamekit_deliver',
     'gripforge_game_capabilities',
     'gripforge_game_project',
+    'gripforge_game_engine',
+    'gripforge_game_content',
     'gripforge_game_play_url',
+    'gripforge_moba_roster',
+    'gripforge_ability_vfx',
+    'gripforge_moba_map',
+    'gripforge_terrain_map_use',
 ];
 const enc = (v) => encodeURIComponent(String(v));
 const HOSTED_DELIVERY_NOTE = 'This hosted endpoint cannot write into your project: write bundle.files following plan.actions in order, or use npx @gripforgeai/mcp with gripforge_gamekit_deliver_local { project_dir }, or the editor bridge.';
@@ -30,7 +37,6 @@ export function registerGameKitTools(register, options, schema = z) {
         .max(120)
         .regex(/^[a-z0-9][a-z0-9._-]*$/i)
         .describe('Kit id from the catalogue, dotted (e.g. vehicle.driveable, mission.objectives).');
-    const range = schema.string().max(80).optional().describe('Semver range to satisfy (e.g. ^1.2.0, 1.x). Default: latest compatible version.');
     const config = schema
         .record(schema.string(), schema.unknown())
         .optional()
@@ -92,11 +98,11 @@ export function registerGameKitTools(register, options, schema = z) {
             delete out[k];
         return out;
     };
-    tool('gripforge_gamekit_search', 'Search the Game Kit catalogue', 'Start here. Search the modular Game Kit catalogue (vehicle.driveable, mission.objectives, npc.wanted, …) by free text, capability, tag or engine target. Pass project_id to score kits against that project: each hit then carries state { installed, updateAvailable, compatible, conflicts, reason } and kits that fill one of its missing capabilities rank first. Returns { kits, presets }; legacy genre kits appear as legacy.* and are installed with gripforge_kit, not here. Kart Racing is native: compose world.racetrack + vehicle.driveable + race.kart; edit race_tracks through project data. world.lighting adds shared sun/fill, point lights and spots, presets, bounded light budgets and bloom; edit world_lights through project data. Call this BEFORE gripforge_gamekit_install. 0 credits.', {
+    tool('gripforge_gamekit_search', 'Search the Game Kit catalogue', 'Start here. Search the modular Game Kit catalogue (vehicle.driveable, mission.objectives, npc.wanted, …) by free text, capability, tag or engine target. Pass project_id to score kits against that project: each hit then carries state { installed, enabled, fills, reason } and kits that fill one of its missing capabilities rank first. Kits are bricks that go together: a kit handling the same thing as an installed one is a same-scene overlap (only one active in a scene), never a reason to skip it. Returns { kits, presets }; each kit carries its presentation: name, tagline (one-line hook), tags, targets and status per engine (web / godot / unity / unreal), and cover / coverUrl, the featured landscape image (WebP) to show the user when proposing kits. legacy.* kits play through their existing client. Kart Racing is native: compose world.racetrack + vehicle.driveable + race.kart; edit race_tracks through project data. world.lighting adds shared sun/fill, point lights and spots, presets, bounded light budgets and bloom; edit world_lights through project data. world.fluids adds interactive mud / blood surfaces, displaced 3D wheel ruts and footprints; edit fluid_surfaces through project data (web renderer). world.terrain adds a seeded large landscape (terrain_edits data), movement.traversal climbing / swimming / gliding with stamina, world.elements data-driven fire, water, ice, electricity and poison (element_rules, element_materials, element_climates data). Call this BEFORE gripforge_gamekit_install. 0 credits.', {
         q: schema.string().max(200).optional().describe('Free text matched on id, name, description and tags (e.g. "drive a car", "wanted level").'),
         capability: schema.string().max(120).optional().describe('Capability the kit must provide (exact id or prefix, e.g. vehicle.drive).'),
         tag: schema.string().max(60).optional().describe('Tag filter (e.g. vehicle, mission, npc, legacy).'),
-        target: schema.enum(['web', 'godot', 'unity', 'unreal']).optional().describe('Engine target the kit must support. Default web.'),
+        target: schema.enum(['web', 'godot', 'unity', 'unreal']).optional().describe('Engine target the kit must support. For game creation, use the engine chosen by the user or identified in their project; ask Unity / Godot / Unreal Engine / Three.js if unknown. The API web default is not user consent.'),
         project_id: projectId.optional().describe('Game Kit project id (gkp_…) to score results against. Default: the workspace’s most recently updated project.'),
         limit: schema.number().int().min(1).max(100).optional().describe('Max kits returned (default 20).'),
     }, { readOnly: true }, (args, extra) => api('gamekits', args, 'GET', extra?.signal, {
@@ -107,7 +113,7 @@ export function registerGameKitTools(register, options, schema = z) {
         project: typeof args.project_id === 'string' ? args.project_id : undefined,
         limit: typeof args.limit === 'number' ? args.limit : undefined,
     }));
-    tool('gripforge_gamekit_get', 'Read one Game Kit', 'Read one Game Kit: its manifest (provides / requires capabilities, asset slots, data collections, events), README docs, config JSON schema with defaults, and published versions. Pass with_usage=true to also list the workspace projects that have it installed. Call this BEFORE gripforge_gamekit_configure to know which config keys exist. 0 credits.', {
+    tool('gripforge_gamekit_get', 'Read one Game Kit', 'Read one Game Kit: its manifest (provides / requires capabilities, asset slots, data collections, events), README docs, config JSON schema with defaults, version and changelog (information only: projects always run the latest version), and summary { tagline, tags, targets, status, cover, coverUrl } with the featured image URL. Pass with_usage=true to also list the workspace projects that have it installed. Call this BEFORE gripforge_gamekit_configure to know which config keys exist. 0 credits.', {
         id: kitId,
         version: schema.string().max(40).optional().describe('Exact version to read (e.g. 1.0.0). Default: latest.'),
         with_usage: schema.boolean().optional().describe('true to include usedBy: the workspace projects where this kit is installed.'),
@@ -115,30 +121,41 @@ export function registerGameKitTools(register, options, schema = z) {
         version: typeof args.version === 'string' ? args.version : undefined,
         with: args.with_usage === true ? 'usage' : undefined,
     }));
-    tool('gripforge_gamekit_install', 'Install a Game Kit into a project', 'Add a modular gameplay kit to a Game Kit project (gkp_…). Dependencies declared in the kit manifest are resolved and added automatically; the response returns the plan (add / upgrade / keep) and the updated capabilities. Pass dry_run=true to preview without writing. Call gripforge_game_capabilities first to see what the project is missing, gripforge_gamekit_search to find the kit, then gripforge_gamekit_configure to tune it. Legacy genre kits (legacy.*) are not installable here — use gripforge_kit. 0 credits.', {
+    tool('gripforge_gamekit_installed', 'Installed kits of a project (use these first)', 'Start here for an existing project. Lists the kits installed in a Game Kit project (gkp_…), first and marked priority: id, name, enabled, addedBy (user / agent / auto / preset / default — the interface kits every new game gets), provides, requires and config, plus the rule that goes with them. Versions are for your information (projects always follow the latest): each kit also has version (in the project), latest, delivered { godot | unity | unreal } (the version the last engine delivery carries — a delivered game can run an older one) and pendingMigrations (manual migrations left to you). Installed kits are choices already made for this game: build on them for what they cover and configure them as needed; search the catalogue only for what they do not cover. 0 credits.', { project_id: projectId }, { readOnly: true }, (args, extra) => api(`gamekit-projects/${enc(args.project_id)}/kits`, args, 'GET', extra?.signal));
+    tool('gripforge_gamekit_install', 'Install a Game Kit into a project', 'Add a gameplay kit (a brick) to a Game Kit project (gkp_…); installing marks that the game uses it. Decide it yourself, no confirmation needed. Always the latest version; dependencies are added automatically and listed in added [{ kit, version, requiredBy, capability }] (e.g. game.engine for a kit that requires it). Kits are bricks that go together: two kits handling the same thing (e.g. two lightings) are a same-scene overlap, never a game-level conflict — only one is active in a scene. Returns { plan, applied, added, project }; dry_run=true previews without writing. Check gripforge_gamekit_installed first, then gripforge_gamekit_search; tune with gripforge_gamekit_configure. Legacy genre kits (legacy.*) use gripforge_kit. 0 credits.', {
         project_id: projectId,
         id: kitId,
-        range,
         config,
         dry_run: schema.boolean().optional().describe('true to return the install plan without writing the project.'),
         allow_planned: schema.boolean().optional().describe('true to accept kits still marked planned (0.x, no runtime yet). Default false.'),
+        reason: schema.string().max(300).optional().describe('One sentence: why you do this, recorded in the project history (required in spirit when you go against the installed-kits rule).'),
     }, { readOnly: false }, (args, extra) => api(`gamekit-projects/${enc(args.project_id)}/kits`, { ...body(args), id: args.id }, 'POST', extra?.signal));
-    tool('gripforge_gamekit_remove', 'Uninstall a Game Kit from a project', 'Uninstall a kit from a Game Kit project (gkp_…). Refused with 409 kit_in_use while other installed kits still require one of its capabilities; pass force=true to remove it anyway and prune=true to also drop the dependencies nothing else needs. Returns { removed[], project }. Call gripforge_gamekit_dependencies BEFORE forcing to see who depends on it. 0 credits.', {
+    tool('gripforge_gamekit_remove', 'Uninstall a Game Kit from a project', 'Uninstall a kit from a Game Kit project (gkp_…). Remove a kit the user installed (addedBy user in gripforge_gamekit_installed) only when the user asks. game.engine (the engine of the game) and the default kits (ui.menu, input.remap, settings.graphics, ui.prompts, ui.endscreen, save.persistence, audio.core, i18n.text, ui.theme, input.virtualpad, addedBy default) are removed only when the user explicitly asks — never to "clean up". A kit other kits depend on, and game.engine always, is not removed by a first call: it answers 409 (kit_in_use, or confirm_required) with details { dependents, confirm } — nothing applied; show the user the dependents, then call again with with_dependents=true and confirm=<token> to remove the kit and its dependents together (the token is bound to the project revision). dry_run=true returns the plan, the dependents and the token without writing. force=true (legacy) removes it and disables its dependents instead; prune=true also drops the dependencies nothing else needs (never game.engine nor a default kit). Returns { applied, removed[], dependents, project }. 0 credits.', {
         project_id: projectId,
         id: kitId,
-        force: schema.boolean().optional().describe('true to remove even when other kits depend on it (their requirements become unresolved).'),
-        prune: schema.boolean().optional().describe('true to also remove dependencies that no remaining kit requires.'),
+        dry_run: schema.boolean().optional().describe('true to return the removal plan (with the dependents and the confirm token) without writing.'),
+        with_dependents: schema.boolean().optional().describe('true to remove the kit AND the kits that depend on it (needs confirm).'),
+        confirm: schema.string().max(80).optional().describe('The confirm token of the previous answer, after the user saw the dependents.'),
+        force: schema.boolean().optional().describe('Legacy: remove even when other kits depend on it; they are disabled, not removed.'),
+        prune: schema.boolean().optional().describe('true to also remove dependencies that no remaining kit requires (never game.engine nor a default kit).'),
+        reason: schema.string().max(300).optional().describe('One sentence: why you do this, recorded in the project history (required in spirit when you go against the installed-kits rule).'),
     }, { readOnly: false, destructive: true }, (args, extra) => api(`gamekit-projects/${enc(args.project_id)}/kits/${enc(args.id)}`, args, 'DELETE', extra?.signal, {
         force: args.force === true ? 1 : undefined,
         prune: args.prune === true ? 1 : undefined,
+        dry_run: args.dry_run === true ? 1 : undefined,
+        with_dependents: args.with_dependents === true ? 1 : undefined,
+        confirm: typeof args.confirm === 'string' && args.confirm ? args.confirm : undefined,
+        reason: typeof args.reason === 'string' && args.reason.trim() ? args.reason : undefined,
     }));
-    tool('gripforge_gamekit_configure', 'Configure an installed Game Kit', 'Tune an installed kit: merge config values validated against the kit configSchema (read it with gripforge_gamekit_get), or toggle enabled to switch the kit off without uninstalling it. Returns { kit, project } with the new project revision. Call this AFTER gripforge_gamekit_install. 0 credits.', {
+    tool('gripforge_gamekit_configure', 'Configure an installed Game Kit', 'Tune an installed kit: merge config values validated against the kit configSchema (read it with gripforge_gamekit_get), or toggle enabled to switch the kit off without uninstalling it. Configure installed kits freely rather than recoding what they do (game.engine: startScene, startEntry, flow.title, story flags). Switching game.engine off follows the confirmation of a removal: the first call answers 409 confirm_required with details.confirm; send it back with enabled=false after the user agreed — never on your own. Returns { kit, project } with the new project revision. Call this AFTER gripforge_gamekit_install. 0 credits.', {
         project_id: projectId,
         id: kitId,
         config,
         enabled: schema.boolean().optional().describe('false to disable the kit at runtime while keeping it installed; true to re-enable.'),
-    }, { readOnly: false }, (args, extra) => api(`gamekit-projects/${enc(args.project_id)}/kits/${enc(args.id)}`, body(args), 'PATCH', extra?.signal));
-    tool('gripforge_gamekit_dependencies', 'Dependency graph of a project or kit', 'Dependency graph of a Game Kit project: nodes (installed kits with version, provides, requires), edges labelled by capability, conflicts and unresolved requirements. Pass project_id for the installed graph; pass a kit id instead to read the declared requires / provides tree of a catalogue kit before installing it. Call this BEFORE gripforge_gamekit_remove with force. 0 credits.', {
+        confirm: schema.string().max(80).optional().describe('game.engine enabled=false: the confirm token of the previous answer.'),
+        reason: schema.string().max(300).optional().describe('One sentence: why you do this, recorded in the project history (required in spirit when you go against the installed-kits rule).'),
+    }, { readOnly: false }, (args, extra) => api(`gamekit-projects/${enc(args.project_id)}/kits/${enc(args.id)}`, { ...body(args), ...(typeof args.confirm === 'string' ? { confirm: args.confirm } : {}) }, 'PATCH', extra?.signal));
+    tool('gripforge_gamekit_dependencies', 'Dependency graph of a project or kit', 'Dependency graph of a Game Kit project: nodes (installed kits with version, provides, requires), edges labelled by capability, same-scene overlaps (conflicts: several enabled providers of one exclusive capability) and unresolved requirements. Pass project_id for the installed graph; pass a kit id instead to read the declared requires / provides tree of a catalogue kit before installing it. Call this BEFORE gripforge_gamekit_remove with force. 0 credits.', {
         project_id: projectId.optional().describe('Game Kit project id (gkp_…). Default: the workspace’s most recently updated project when id is not given.'),
         id: kitId.optional().describe('Catalogue kit id to inspect instead of a project (returns its manifest tree).'),
     }, { readOnly: true }, (args, extra) => {
@@ -148,11 +165,10 @@ export function registerGameKitTools(register, options, schema = z) {
             return Promise.resolve(fail('Pass project_id (gkp_…) or a kit id.'));
         return api(`gamekit-projects/${enc(args.project_id)}/dependencies`, args, 'GET', extra?.signal);
     });
-    tool('gripforge_gamekit_update', 'Check or apply Game Kit updates', 'Check or apply kit updates in a Game Kit project. Dry-run by default: returns the plan (from / to version, breaking changes, migrations to run) without writing. Pass apply=true to write the new lockfile and run the migrations; range narrows the target version (e.g. ^1.2.0). Omit id to check every installed kit in one call. Call gripforge_gamekit_get on the target version to read its manifest first. 0 credits.', {
+    tool('gripforge_gamekit_update', 'Bring Game Kits to their latest version', 'Projects always follow the latest version of their kits: the studio updates them automatically when a project is opened. Use this to do it now. Dry-run by default: returns the plan (from / to version, migrations). Pass apply=true to apply it. A migration with auto=false is never applied by itself: it is your task — apply its note (config, data) then call again. Omit id to check every installed kit. 0 credits.', {
         project_id: projectId,
         id: kitId.optional().describe('Installed kit to update. Omit to check every installed kit.'),
-        range,
-        apply: schema.boolean().optional().describe('true to apply the update (new lockfile + migrations). Default false = plan only.'),
+        apply: schema.boolean().optional().describe('true to apply the update to the latest version (automatic migrations run). Default false = plan only.'),
     }, { readOnly: false }, async (args, extra) => {
         const project = enc(args.project_id);
         const payload = body(args);
@@ -178,12 +194,11 @@ export function registerGameKitTools(register, options, schema = z) {
         const data = { project_id: args.project_id, kits };
         return { ...(isError ? { isError: true } : {}), structuredContent: data, content: [{ type: 'text', text: JSON.stringify(data) }] };
     });
-    tool('gripforge_gamekit_deliver', 'Deliver Game Kits into an engine project', 'Turn catalogue kits, or the enabled kits of a Game Kit project, into engine files: Godot gets GDScript, scenes and config under gripforge/kits/<kit>/, Unity and Unreal get recipes, web needs nothing. Call with dry_run=true FIRST: it returns the plan (files to add / keep / modify / delete, conflicts, dependencies, post-install steps) and never charges. Pass project_state (the current gripforge/gamekits.lock.json, path → sha256 of the files under gripforge/, engineVersion) so updates keep your edits and detect conflicts. Then call without dry_run to get the bundle. The hosted endpoint cannot write into your project: write bundle.files following plan.actions in order (backup, write, writeBin from bundle.binaries, delete with .uid / .import siblings, writeLock with bundle.lock), or use the npm client with project_dir (gripforge_gamekit_deliver_local), or the editor bridge. A blocked plan answers 409 with the plan: force backs up then overwrites edited files, accept_breaking allows a major update. Credits: the first delivery of a kit major version to an engine costs 1 credit per workspace; re-deliveries, updates within a major, dry runs and the web target are free.', {
-        target: schema.enum(['godot', 'unity', 'unreal', 'web']).describe('Engine to deliver to: godot (files), unity / unreal (recipes), web (native, nothing to write).'),
+    tool('gripforge_gamekit_deliver', 'Deliver Game Kits into an engine project', 'Turn catalogue kits, or the enabled kits of a Game Kit project, into engine files: Godot gets GDScript, scenes and config under gripforge/kits/<kit>/, Unity gets an embedded UPM package plus C# files and Unreal a Blueprint-first plugin for every kit with an engine delivery (gameplay and net.* kits; recipes otherwise), web needs nothing. Kits always deliver at their latest version; a kit the project copied locally is delivered from its copy. Call with dry_run=true FIRST: it returns the plan (files to add / keep / modify / delete, conflicts, dependencies, post-install steps) and never charges. Pass project_state (the current gripforge/gamekits.lock.json, path → sha256 of the files under gripforge/, engineVersion) so updates keep your edits and detect conflicts. Then call without dry_run to get the bundle. The hosted endpoint cannot write into your project: write bundle.files following plan.actions in order (backup, write, writeBin from bundle.binaries, delete with .uid / .import siblings, writeLock with bundle.lock), or use the npm client with project_dir (gripforge_gamekit_deliver_local), or the editor bridge. A blocked plan answers 409 with the plan: a file edited in the engine project is reported (modified_file), never overwritten silently; force backs it up then overwrites it. Credits: the first delivery of a kit major version to an engine costs 1 credit per workspace; re-deliveries, updates within a major, dry runs and the web target are free.', {
+        target: schema.enum(['godot', 'unity', 'unreal', 'web']).describe('Engine to deliver to: godot (addon + kit files), unity (UPM package + C# files), unreal (plugins), web (native, nothing to write). Kits without an engine delivery get recipes.'),
         kits: schema
             .array(schema.object({
             id: kitId,
-            version: schema.string().max(40).optional().describe('Exact version; only the latest is deliverable. Default latest.'),
             config: schema.record(schema.string(), schema.unknown()).optional().describe('Kit config, validated against its configSchema.'),
             bindings: schema.record(schema.string(), schema.string()).optional().describe('Asset slot → Library item id (lib_…).'),
         }))
@@ -202,7 +217,6 @@ export function registerGameKitTools(register, options, schema = z) {
             .describe('What the engine project contains now. Without it the plan assumes an empty project (add-only).'),
         dry_run: schema.boolean().optional().describe('true → plan only: no bundle, never charged. Do this first.'),
         force: schema.boolean().optional().describe('true → back up then overwrite edited managed files and existing seed files.'),
-        accept_breaking: schema.boolean().optional().describe('true → allow a breaking (major) update.'),
     }, { readOnly: false }, async (args, extra) => {
         const kits = Array.isArray(args.kits) ? args.kits : [];
         const state = args.project_state;
@@ -217,7 +231,6 @@ export function registerGameKitTools(register, options, schema = z) {
             project: args.project_state,
             dryRun: args.dry_run === true,
             force: args.force === true,
-            acceptBreaking: args.accept_breaking === true,
         }, 'POST', extra?.signal);
         const data = result.structuredContent;
         if (result.isError || !data?.bundle)
@@ -225,19 +238,19 @@ export function registerGameKitTools(register, options, schema = z) {
         const withNote = { ...data, note: HOSTED_DELIVERY_NOTE };
         return { structuredContent: withNote, content: [{ type: 'text', text: JSON.stringify(withNote) }] };
     });
-    tool('gripforge_game_capabilities', 'Capabilities report of a project', 'Start here for an existing project. Report the capabilities a Game Kit project provides, what is still missing for a goal (a preset id from gripforge_gamekit_search or a comma-separated list of capabilities) and which catalogue kits would fill each gap. Call this BEFORE gripforge_gamekit_install to pick the next kit. 0 credits.', {
+    tool('gripforge_game_capabilities', 'Capabilities report of a project', 'Report the capabilities a Game Kit project provides, what is still missing for a goal (a preset id from gripforge_gamekit_search or a comma-separated list of capabilities) and which catalogue kits would fill each gap. The installed kits (gripforge_gamekit_installed) come first; call this BEFORE gripforge_gamekit_install to pick the next kit. 0 credits.', {
         project_id: projectId,
         goal: schema.string().max(400).optional().describe('Preset id (e.g. from gripforge_gamekit_search presets) or comma-separated capabilities to reach. Default: the project’s own preset.'),
     }, { readOnly: true }, (args, extra) => api(`gamekit-projects/${enc(args.project_id)}/capabilities`, args, 'GET', extra?.signal, {
         goal: typeof args.goal === 'string' ? args.goal : undefined,
     }));
-    tool('gripforge_game_project', 'List, create, read, bind, feed or delete Game Kit projects', 'Manage Game Kit projects (gkp_…): the container holding installed kits, their lockfile, asset bindings and data collections. action=list lists the workspace projects; create needs name and takes a preset (see gripforge_gamekit_search) or an explicit kits map; get returns the full ProjectDetail (installed kits, bindings, capabilities, missing, playUrl); bind maps asset slots to Library items (lib_…, null to clear); data reads a collection or upserts / removes documents validated against the kits’ schemas (replace=true swaps the whole collection); delete needs confirm=true. Call this first to create or pick the project, then gripforge_gamekit_install. 0 credits.', {
+    tool('gripforge_game_project', 'List, create, read, bind, feed or delete Game Kit projects', 'Manage Game Kit projects (gkp_…): the container holding installed kits, their lockfile, asset bindings and data collections. action=list lists the workspace projects; create needs name and takes a preset (see gripforge_gamekit_search; adventure is the reference game of game.engine) or an explicit kits map — every new project gets game.engine first (the engine of the game: scenes, archetypes, scripts, life cycle; its answer carries the engine start pack { structure, scene, blocks, order, next, rules } and added, the kits installed for dependencies), then the default kits ui.menu (title / pause / options / load and save screen), input.remap (key remapping), settings.graphics (graphics options), ui.prompts (on-screen key prompts that follow remapping and the gamepad), ui.endscreen (end screen and credits), save.persistence (save slots, quick save, autosave), audio.core (game audio: mixer, music, effects, event → sound table), i18n.text (game texts in the player’s language: translation tables in the translations collection, ICU plurals) ui.theme (the design of every interface as kit config: colours, font, shapes, key glyphs; unset = built-in look) and input.virtualpad (the on-screen gamepad of touch screens, mode auto: shown on a touch screen without a gamepad, Touch controls tab), addedBy default: keep and configure them, leave one out ({ "ui.menu": false }) or remove it only if the user asks; get returns the full ProjectDetail (installed kits, bindings, capabilities, missing, playUrl); bind maps asset slots to Library items (lib_…, null to clear); data reads a collection or upserts / removes documents validated against the kits’ schemas (replace=true swaps the whole collection); delete needs confirm=true. Call this first to create or pick the project, then gripforge_gamekit_installed (existing project) or gripforge_gamekit_install. 0 credits.', {
         action: schema.enum(['list', 'create', 'get', 'bind', 'data', 'delete']).describe('list | create | get | bind | data | delete.'),
         project_id: projectId.optional().describe('Game Kit project id (gkp_…). Required for get, bind, data and delete.'),
         name: schema.string().min(1).max(120).optional().describe('create: project name.'),
         preset: schema.string().max(80).optional().describe('create: preset id whose default kits are installed (gripforge_gamekit_search returns presets).'),
-        kits: schema.record(schema.string(), schema.boolean()).optional().describe('create: explicit kit toggles { "vehicle.driveable": true, … } on top of the preset. Unchecking a required kit fails with toggle_requires.'),
-        target: schema.enum(['web', 'godot', 'unity', 'unreal']).optional().describe('create: engine target. Default web.'),
+        kits: schema.record(schema.string(), schema.boolean()).optional().describe('create: explicit kit toggles { "vehicle.driveable": true, … } on top of the preset. Unchecking a required kit fails with toggle_requires. The default kits (ui.menu, input.remap, settings.graphics, ui.prompts, ui.endscreen, save.persistence, audio.core, i18n.text, ui.theme, input.virtualpad) are included unless set to false here — only when the user asked for it.'),
+        target: schema.enum(['web', 'godot', 'unity', 'unreal']).optional().describe('create: pass the confirmed engine explicitly (Three.js=web). Ask the user to choose Unity / Godot / Unreal Engine / Three.js before creating if unknown. API default web is for compatibility, not an engine choice.'),
         bindings: schema.record(schema.string(), schema.string().nullable()).optional().describe('bind: { slot: lib_… | null } — Library item per asset slot declared by the installed kits, null clears.'),
         collection: schema.string().max(80).optional().describe('data: collection name declared by an installed kit (e.g. missions, npcs, zones).'),
         documents: schema.array(schema.record(schema.string(), schema.unknown())).max(500).optional().describe('data: documents to upsert (each with its id), validated against the kit schema.'),
@@ -278,6 +291,51 @@ export function registerGameKitTools(register, options, schema = z) {
         }
         return Promise.resolve(fail(`Unknown action ${action}.`));
     });
+    tool('gripforge_game_engine', 'The engine of a game: structure, bricks, report, next steps', 'Read game.engine of a Game Kit project (gkp_…) — a direction, never a gate. action=start (default): the start pack { version, active, structure { engine, kits, content counts, code }, scene, blocks digest, order (scene → playable → assets → archetypes → story → scripts → ui → validate → deliver → code), next [{ step, tool, args, why }], code (where game code goes per engine), rules } and the full content report. action=blocks: the brick catalogue computed from the manifests — entity kinds, archetype components (kit, schema, example), script verbs (conditions / actions with arguments and shorthand), script sugars (interact, enter, leave, scene, talked, quest, state, gives), quest step types, NPC behaviours, worlds, layers, events, variables; scope=catalog adds the bricks of kits not installed (install <kit>). action=report: { ok, errors, warnings, stats } — an error means that piece is left out of the game (the rest plays), a warning that it loads with something missing; each issue may carry a fix { tool, args }. action=next: the next steps only. A game with everything in code is valid: content first, kits second, code for the rest. 0 credits.', {
+        project_id: projectId,
+        action: schema.enum(['start', 'structure', 'blocks', 'report', 'next']).optional().describe('start (default) | structure | blocks | report | next.'),
+        scope: schema.enum(['installed', 'catalog']).optional().describe('blocks: installed (default) or catalog.'),
+        scene: schema.string().max(64).optional().describe('start: also return this scene document.'),
+    }, { readOnly: true }, async (args, extra) => {
+        const action = typeof args.action === 'string' ? args.action : 'start';
+        const project = enc(args.project_id);
+        if (action === 'blocks')
+            return api(`gamekit-projects/${project}/engine/blocks`, args, 'GET', extra?.signal, { scope: typeof args.scope === 'string' ? args.scope : undefined });
+        const res = await api(`gamekit-projects/${project}/engine`, args, 'GET', extra?.signal, { scene: typeof args.scene === 'string' ? args.scene : undefined });
+        if (res.isError || action === 'start')
+            return res;
+        const data = res.structuredContent;
+        const picked = action === 'report' ? { report: data?.report } : action === 'next' ? { next: data?.engine?.next, order: data?.engine?.order } : { structure: data?.engine?.structure, scene: data?.engine?.scene, active: data?.engine?.active };
+        return { structuredContent: picked, content: [{ type: 'text', text: JSON.stringify(picked) }] };
+    });
+    tool('gripforge_game_content', 'Drop content into a game: scenes, archetypes, scripts, quests…', 'Read and write the content of a Game Kit project (gkp_…) — what game.engine builds the game from, no engine code needed. kind: archetype (an entity template: kind prop|npc|…, asset { item: lib_… } bound to content:<id> | { slot }, components claimed by kits — see gripforge_game_engine blocks — and gives { quest, offer, progress?, thanks? } for "this NPC gives this quest"), scene (world { kit, config?, doc? }, entries, instances [{ id, archetype, at, yaw?, place?, set? }], zones, layers, ui), script (gripforge.script/1: { id, on: <instance> | archetype:<id> | scene:<id>, rules: [{ when, if?, then, else?, once? }] } with sugars { "interact": "self" }, { "enter": zone }, { "state": { open: false } }, { "quest": id, "is": "completed" }, { "talked": npc }, engine verbs set_state, play_clip, set_solid, show, hide, enable_script, disable_script, load_scene, end_game, call, set_talk and kit verbs as shorthand { "give_item": "key" }), mission (alias quest), dialogue, npc, item, translations, code_module (what game code registers: verbs, components, services, entity kinds), zone, trigger. action=list (kind optional: counts), get (kind, id), put (kind, doc or docs: upsert, validated against the declaring kit schema), remove (kind, id), validate (dry run of a put: the report it would give), place (scene, archetype or asset lib_…, at, yaw?, id?, place ground|none: the placement on the ground is baked once on the server, the same on every engine), bake (re-bake the placements of a scene after its world changed). Writes return the content report after the change; the report never refuses a write — only a document invalid for its schema is. 0 credits.', {
+        project_id: projectId,
+        action: schema.enum(['list', 'get', 'put', 'remove', 'validate', 'place', 'bake']).describe('list | get | put | remove | validate | place | bake.'),
+        kind: schema.enum(['archetype', 'scene', 'script', 'mission', 'quest', 'dialogue', 'npc', 'item', 'translations', 'code_module', 'zone', 'trigger']).optional().describe('The content kind (list without kind: counts per kind).'),
+        id: schema.string().max(120).optional().describe('get / remove: the document id; place: the instance id (default <archetype>_<n>).'),
+        doc: schema.record(schema.string(), schema.unknown()).optional().describe('put / validate: the document (with its id).'),
+        docs: schema.array(schema.record(schema.string(), schema.unknown())).max(200).optional().describe('put / validate: several documents of the same kind.'),
+        scene: schema.string().max(64).optional().describe('place / bake: the scene id (place default: the first scene).'),
+        archetype: schema.string().max(64).optional().describe('place: the archetype of the instance.'),
+        asset: schema.string().max(64).optional().describe('place: a Library asset (lib_…) instead of an archetype: its archetype is the one using it, or a new prop.'),
+        at: schema.array(schema.number()).length(3).optional().describe('place: position [x, y, z] in metres (+Y up).'),
+        yaw: schema.number().optional().describe('place: rotation around +Y in radians.'),
+        place: schema.enum(['ground', 'none']).optional().describe('place: ground (default) snaps to the scene ground; none keeps y.'),
+        set: schema.record(schema.string(), schema.unknown()).optional().describe('place: component overrides of this instance.'),
+        dry_run: schema.boolean().optional().describe('put / remove: validate and report without writing.'),
+    }, { readOnly: false }, (args, extra) => {
+        const action = String(args.action);
+        const project = enc(args.project_id);
+        if (action === 'list' || action === 'get') {
+            if (action === 'get' && (typeof args.kind !== 'string' || typeof args.id !== 'string'))
+                return Promise.resolve(fail('get needs kind and id.'));
+            return api(`gamekit-projects/${project}/content`, args, 'GET', extra?.signal, { kind: typeof args.kind === 'string' ? args.kind : undefined, id: typeof args.id === 'string' ? args.id : undefined });
+        }
+        const { project_id: _p, ...payload } = args;
+        if (action === 'place')
+            return api(`gamekit-projects/${project}/content/place`, payload, 'POST', extra?.signal);
+        return api(`gamekit-projects/${project}/content`, payload, 'POST', extra?.signal);
+    });
     tool('gripforge_game_play_url', 'Play URL of a Game Kit project', 'Get the browser play URL of a Game Kit project so a human (or a screenshot step) can run its current revision in the web runtime. Reads the project bundle and returns { url, absolute }; absolute is built on the GripForge origin of this key. Call it AFTER gripforge_gamekit_install or gripforge_game_project bind to check the result live. 0 credits.', { project_id: projectId }, { readOnly: true }, async (args, extra) => {
         const res = await api(`gamekit-projects/${enc(args.project_id)}/bundle`, args, 'GET', extra?.signal);
         if (res.isError)
@@ -295,4 +353,55 @@ export function registerGameKitTools(register, options, schema = z) {
         const data = { url: playUrl, absolute };
         return { structuredContent: data, content: [{ type: 'text', text: JSON.stringify(data) }] };
     });
+    tool('gripforge_moba_roster', 'Set the champions of a MOBA project', 'Turn champions into the playable roster of a moba project (preset "moba"). Pass the Library ids of 1 to 10 champions that carry an ability pack (the items made by gripforge_abilities_generate: rigged model + basic_attack and ability_q…r clips). Writes the moba_heroes and abilities collections (ids <hero>__ability_q), binds each champion to moba_hero_<n> and the player\'s champion (player, else the first) to player_character. Bots play the other champions. Returns the heroes with their attack and Q/W/E/R. Then gripforge_game_play_url to play. 0 credits.', {
+        project_id: projectId,
+        heroes: schema.array(schema.string()).min(1).max(10).describe('Library ids (lib_…) of champions with an ability pack, in roster order.'),
+        player: schema.string().optional().describe('The champion the player controls (one of heroes); default the first.'),
+    }, { readOnly: false }, async (args, extra) => {
+        const { project_id, ...body } = args;
+        return api(`gamekit-projects/${enc(project_id)}/moba-roster`, body, 'PUT', extra?.signal);
+    });
+    tool('gripforge_ability_vfx', 'Give every ability of a game its cast effect', 'Write and bind a cast effect for each ability of a Game Kit project that has none: an area gets a ground shockwave, a line a bolt and its trail, an arc a sweeping crescent, a self cast a rising aura; colour from the ability\'s words (fire, frost, wind, holy…), size from its range, ultimates larger. The project needs the fx.ability_vfx kit (the moba preset installs it) and an abilities collection (gripforge_moba_roster writes it). Effects are procedural sources saved as VFX items and bound to ability_vfx:<ability id>, immediately. replace: true rewrites the existing ones; abilities limits to some ids. A hand-made or generated VFX bound to the same slot takes over. 0 credits.', {
+        project_id: projectId,
+        replace: schema.boolean().optional().describe('Rewrite abilities that already have an effect (default: keep them).'),
+        abilities: schema.array(schema.string()).max(80).optional().describe('Only these ability ids (default: all).'),
+    }, { readOnly: false }, async (args, extra) => {
+        const { project_id, ...body } = args;
+        return api(`gamekit-projects/${enc(project_id)}/ability-vfx`, body, 'POST', extra?.signal);
+    });
+    tool('gripforge_moba_map', 'Generate, dress, check and set the map of a MOBA project', 'The map of a moba project as a gameplay plan: bounds, team bases and spawns, 1 to 5 lanes (the minions\' paths), structure slots (towers, inhibitors, nexus), jungle zones and camp slots, objective zones, the divider (river: walkable; chasm, lava, void: crossed only at bridges), crossings, bush zones, walls, camera limits and symmetry. action "generate" builds a fair map (mirrored through the centre) from lanes, divider, size, team_size, camps_per_jungle, objectives, bushes, walls and returns it with a playability report; apply: true puts it in the project (moba_maps, the match\'s map and team size, the camera turn). action "validate" checks a map you pass, or the project\'s: every lane open end to end, spawns, structures and camps reachable, nothing out of bounds, the declared symmetry respected. action "set" stores an edited map document (refused while it has errors, unless force). action "get" returns the current map and its report. New maps default to style {theme: "sanctum", detail: "high", seed: 11, relief: "landscape"}. action "dress" previews a reusable procedural finish for the current map: jungle plateaus, river banks and paved fords, terraced bases, walkable staircases, carved structures, clustered forests, stone guardians and lilies; apply: true saves only the map document, keeping its lane layout and camera configuration; relief updates the shared terrain mesh, ground queries and stair collisions; landscape is the default, terraced keeps base terraces only, flat keeps a level arena. Themes: sanctum, wildwood, ashen; detail: low, medium, high; seed makes the finish repeatable. Bound Library models and textures take precedence. The scenery kit dresses walls and bushes with the bound models. 0 credits.', {
+        project_id: projectId,
+        action: schema.enum(['get', 'generate', 'dress', 'validate', 'set']).optional().describe('Default: get. dress previews a finish for the existing map, without rebuilding its layout; apply: true saves it.'),
+        style: schema.object({
+            relief: schema.enum(['landscape', 'terraced', 'flat']).optional().describe('Default landscape: jungle plateaus, river banks and terraced gardens; shared terrain mesh, physics and unit heights. terraced keeps only the gardens; flat keeps a level map.'),
+            theme: schema.enum(['sanctum', 'wildwood', 'ashen']).optional().describe('sanctum: pale carved stone, gold, contrasting groves and lilies; wildwood: mossy forest; ashen: weathered volcanic stone. Default: sanctum.'),
+            detail: schema.enum(['low', 'medium', 'high']).optional().describe('Procedural decoration budget, default high. Navigation is identical at all levels.'),
+            seed: schema.number().int().min(0).max(2147483646).optional().describe('Repeatable finish, default 11.'),
+        }).strict().optional().describe('generate / dress: art direction stored with the map. Paved lanes, inset seals, bevelled stone borders, banks, plants, lilies and entrance lights. Bound Library models and textures take precedence.'),
+        lanes: schema.number().int().min(1).max(5).optional().describe('generate: number of lanes (default 3).'),
+        divider: schema.enum(['river', 'chasm', 'lava', 'void', 'none']).optional().describe('generate: what separates the halves (default river).'),
+        size: schema.number().min(100).max(400).optional().describe('generate: side of the square map in metres.'),
+        team_size: schema.number().int().min(1).max(5).optional().describe('generate: heroes per team (default 3 for one lane, 5 otherwise).'),
+        camps_per_jungle: schema.number().int().min(0).max(3).optional().describe('generate: small camps in each jungle (default 2).'),
+        objectives: schema.number().int().min(0).max(4).optional().describe('generate: epic objectives on the divider.'),
+        bushes: schema.boolean().optional().describe('generate: stealth bushes along the lanes (default true).'),
+        walls: schema.boolean().optional().describe('generate: rock walls behind the camps (default true).'),
+        id: schema.string().max(41).optional().describe('generate: id of the new map (lowercase, digits, _).'),
+        name: schema.string().max(80).optional().describe('generate: display name of the map.'),
+        apply: schema.boolean().optional().describe('generate / dress: store the result in the project (default: preview only).'),
+        map: schema.record(schema.string(), schema.unknown()).optional().describe('validate / set: a full map document.'),
+        force: schema.boolean().optional().describe('set: store a map that has errors.'),
+    }, { readOnly: false }, async (args, extra) => {
+        const { project_id, ...body } = args;
+        return api(`gamekit-projects/${enc(project_id)}/moba-map`, body, 'POST', extra?.signal);
+    });
+    tool('gripforge_terrain_map_use', 'Play a terrain studio map in a game', 'Make a map of the terrain studio the world of a game that has the world.terrain kit. Pass map (a terrain studio map id, lvl_…) or scene (a scene id, with terrain when the scene has several terrain nodes). The map is baked once into a file (heights, ground roles, lakes and rivers, vegetation, roads, spawn and objective points) stored in the Library and bound to the terrain_map slot; the project data keeps its reference in terrain_maps. The same file is delivered to Godot, Unity and Unreal with the kit. Buildings and other non-vegetation props, and terrain holes, are not carried yet (counted in map.notCarried). Without a bound map world.terrain keeps generating its world from the seed. 0 credits.', {
+        project_id: projectId,
+        map: schema.string().optional().describe('Terrain studio map id (lvl_…).'),
+        scene: schema.string().optional().describe('Scene id whose terrain node becomes the world (instead of map).'),
+        terrain: schema.string().optional().describe('Terrain node id in the scene (default: its first terrain).'),
+    }, { readOnly: false }, async (args, extra) => {
+        const { project_id, ...body } = args;
+        return api(`gamekit-projects/${enc(project_id)}/terrain-map`, body, 'PUT', extra?.signal);
+    });
 }

package/dist/hero-ability-tools.js

@@ -0,0 +1,48 @@
+import { z } from 'zod/v4';
+export const HERO_ABILITY_TOOL_NAMES = ['gripforge_abilities_generate'];
+/**
+ * A hero's abilities ready in Character Studio: kit (role, basic attack, passive, Q/W/E/R), the
+ * Kimodo clip of each cast on the character, and the gripforge.abilities/1 pack bound to them.
+ * Hosted and local MCP share the same REST workflow: stage=plan (free), then stage=build.
+ */
+export function registerHeroAbilityTools(register, options, schema = z) {
+    const shape = {
+        stage: schema.enum(['plan', 'build']).optional().describe('plan (default, free): the kit, its abilities and clips, and the price. build: queue the GPU job.'),
+        prompt: schema.string().min(8).max(600).optional().describe('The hero in one sentence when there is no concept, e.g. "a frost archer who slows enemies, ultimate freezes an area". Its kit is written at plan.'),
+        hero_concept_id: schema.string().optional().describe('A hero concept with an ability kit (gripforge_game_concepts with hero_kits).'),
+        kit: schema.record(schema.string(), schema.unknown()).optional().describe('The kit returned by plan: pass it to build to keep exactly what was shown.'),
+        name: schema.string().min(2).max(80).optional(),
+        character_id: schema.string().optional().describe('Rigged Library character or enemy the clips and abilities go on. Default: the UAL mannequin.'),
+        workspace_id: schema.string().max(100).optional(),
+        idempotency_key: schema.string().regex(/^[a-zA-Z0-9_.:-]{8,160}$/).optional(),
+    };
+    register(HERO_ABILITY_TOOL_NAMES[0], {
+        title: 'Generate hero abilities',
+        description: 'A hero\'s abilities ready to play in Character Studio: the kit (role, lane, basic attack, passive + Q/W/E/R with type, range, cooldown, cost, effect, VFX brief, cast animation) from a hero concept or written from one sentence; the basic attack and Q/W/E/R casts animated with NVIDIA Kimodo on the rigged character; and the gripforge.abilities/1 pack (targeting, damage/heal, timings) bound to those clips and stored on the result. Call stage=plan first (free) and show the abilities and price (1 credit per clip, 5 for a kit); then stage=build with the returned kit. Poll gripforge_generation_read with job_id; result.studio_url opens the Abilities tab. Numbers are starting values, not a balance pass; VFX lines are briefs for gripforge_vfx_generate.',
+        inputSchema: shape,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (args, extra) => {
+        const parsed = schema.object(shape).strict().safeParse(args);
+        if (!parsed.success)
+            return { isError: true, content: [{ type: 'text', text: parsed.error.message }] };
+        const key = options.getApiKey();
+        if (!key)
+            return { isError: true, content: [{ type: 'text', text: 'GripForge API key required.' }] };
+        const { workspace_id, ...body } = parsed.data;
+        try {
+            const response = await fetch(options.apiUrl.replace(/\/$/, '') + '/api/v1/abilities/generate', {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', 'x-gripforge-client': 'mcp', 'x-api-key': key, ...(typeof workspace_id === 'string' ? { 'x-workspace-id': workspace_id } : {}) },
+                body: JSON.stringify(body),
+                signal: AbortSignal.any([AbortSignal.timeout(120_000), ...(extra?.signal ? [extra.signal] : [])]),
+            });
+            const data = await response.json();
+            if (typeof data.status_url === 'string' && data.status_url.startsWith('/'))
+                data.status_url = new URL(data.status_url, options.apiUrl).href;
+            return { ...(!response.ok ? { isError: true } : {}), structuredContent: data, content: [{ type: 'text', text: JSON.stringify(data) }] };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: 'text', text: error instanceof Error ? error.message : 'Ability request failed.' }] };
+        }
+    });
+}

package/dist/joystick-kit/godot.js

@@ -0,0 +1,146 @@
+export function godotJoystickFiles(c) {
+    return [{ path: 'gripforge/joystick/virtual_stick.gd', content: `extends Control
+## GripForge input.joystick: persistent analog state, one pointer per stick.
+signal axis_changed(value: Vector2)
+@export_range(0.0, 0.5) var deadzone: float = ${c.deadzone}
+@export var accent: Color = Color("${c.accent}")
+var axis := Vector2.ZERO
+var visual := Vector2.ZERO
+var pointer := -1
+
+func _ready() -> void:
+	mouse_filter = Control.MOUSE_FILTER_IGNORE
+	resized.connect(reset)
+
+static func radial(value: Vector2, zone: float) -> Vector2:
+	var magnitude := value.length()
+	if magnitude <= zone: return Vector2.ZERO
+	return value / magnitude * minf(1.0, (magnitude - zone) / (1.0 - zone))
+
+func update_pointer(screen_position: Vector2) -> void:
+	var local := get_global_transform_with_canvas().affine_inverse() * screen_position
+	var travel := minf(size.x, size.y) * 0.325
+	if travel <= 0.0: return
+	var raw := (local - size * 0.5) / travel
+	visual = raw.limit_length()
+	axis = radial(Vector2(raw.x, -raw.y), deadzone)
+	axis_changed.emit(axis)
+	queue_redraw()
+
+func _input(event: InputEvent) -> void:
+	if not is_visible_in_tree():
+		reset()
+		return
+	if event is InputEventScreenTouch:
+		if event.canceled and pointer == event.index:
+			reset()
+			get_viewport().set_input_as_handled()
+		elif event.pressed and not event.canceled and pointer == -1 and get_global_rect().has_point(event.position):
+			pointer = event.index
+			update_pointer(event.position)
+			get_viewport().set_input_as_handled()
+		elif not event.pressed and pointer == event.index:
+			reset()
+			get_viewport().set_input_as_handled()
+	elif event is InputEventScreenDrag and pointer == event.index:
+		update_pointer(event.position)
+		get_viewport().set_input_as_handled()
+	elif event is InputEventMouseButton and event.button_index == MOUSE_BUTTON_LEFT:
+		if event.pressed and pointer == -1 and get_global_rect().has_point(event.position):
+			pointer = -2
+			update_pointer(event.position)
+			get_viewport().set_input_as_handled()
+		elif not event.pressed and pointer == -2:
+			reset()
+			get_viewport().set_input_as_handled()
+	elif event is InputEventMouseMotion and pointer == -2:
+		update_pointer(event.position)
+		get_viewport().set_input_as_handled()
+
+func reset() -> void:
+	pointer = -1
+	axis = Vector2.ZERO
+	visual = Vector2.ZERO
+	axis_changed.emit(axis)
+	queue_redraw()
+
+func _notification(what: int) -> void:
+	if what == NOTIFICATION_APPLICATION_FOCUS_OUT or what == NOTIFICATION_EXIT_TREE:
+		reset()
+
+func _draw() -> void:
+	var radius := minf(size.x, size.y) * 0.5
+	draw_circle(size * 0.5, radius, Color(0.06, 0.08, 0.11, 0.72))
+	draw_arc(size * 0.5, maxf(0, radius - 1), 0, TAU, 64, Color(1, 1, 1, 0.22), 2, true)
+	draw_circle(size * 0.5 + visual * radius * 0.65, radius * 0.28, accent)
+` }, { path: 'gripforge/joystick/joystick_rig.gd', content: `extends CanvasLayer
+## Add this script to a CanvasLayer. No InputMap mutation or autoload required.
+const Stick = preload("res://gripforge/joystick/virtual_stick.gd")
+@export var dual: bool = ${c.layout === 'dual' ? 'true' : 'false'}
+@export_range(32, 160) var radius: float = ${c.radius}
+@export_range(0, 0.5) var deadzone: float = ${c.deadzone}
+var left: Control
+var right: Control
+
+func _ready() -> void:
+	layer = 20
+	left = Stick.new()
+	left.deadzone = deadzone
+	add_child(left)
+	if dual:
+		right = Stick.new()
+		right.deadzone = deadzone
+		add_child(right)
+	get_viewport().size_changed.connect(_layout)
+	_layout()
+
+func _layout() -> void:
+	var view := get_viewport().get_visible_rect().size
+	var r := minf(radius, maxf(24, (view.x - 72) / (4 if dual else 2)))
+	left.size = Vector2.ONE * r * 2
+	left.position = Vector2(24, maxf(0, view.y - 24 - r * 2))
+	left.reset()
+	if right:
+		right.size = left.size
+		right.position = Vector2(view.x - 24 - r * 2, left.position.y)
+		right.reset()
+
+func movement() -> Vector2:
+	return left.axis if is_instance_valid(left) else Vector2.ZERO
+
+func look() -> Vector2:
+	return right.axis if is_instance_valid(right) else Vector2.ZERO
+` }, { path: 'gripforge/joystick/joystick.tscn', content: `[gd_scene load_steps=2 format=3]
+[ext_resource type="Script" path="res://gripforge/joystick/joystick_rig.gd" id="1"]
+[node name="GripForgeJoystick" type="CanvasLayer"]
+script = ExtResource("1")
+` }, { path: 'gripforge/joystick/character_example.gd', content: `extends CharacterBody3D
+## Optional example; merge input reads into your own motor instead of running two motors.
+@export var joystick: CanvasLayer
+@export var camera: Node3D
+@export var speed: float = 5.0
+@export var gravity: float = 9.8
+func _physics_process(delta: float) -> void:
+	var axes: Vector2 = joystick.movement() if joystick else Vector2.ZERO
+	var yaw: float = camera.global_rotation.y if camera else global_rotation.y
+	var direction := Basis(Vector3.UP, yaw) * Vector3(axes.x, 0, -axes.y)
+	velocity.x = direction.x * speed
+	velocity.z = direction.z * speed
+	if not is_on_floor(): velocity.y -= gravity * delta
+	else: velocity.y = 0
+	move_and_slide()
+` }, { path: 'README.md', content: `# GripForge joystick · Godot 4.2+
+
+Copy gripforge/ into res://. Instance joystick.tscn in the gameplay scene.
+Read movement() and look() every physics frame. X is right; Y is forward/up.
+Assign the rig and camera in the optional CharacterBody3D example. A collider and
+floor are still supplied by your game; the joystick does not replace collision.
+
+Touch IDs are isolated; both sticks can be held simultaneously. Mouse testing is
+built in: you do not need to enable Emulate Touch From Mouse. Keep only one such
+emulation path active. Release, focus loss, resizing and removal reset the axes.
+The rig does not erase keyboard/gamepad bindings. Combine its movement vector with
+your existing input source in your motor (choose one source per frame, then clamp
+the combined length to one). Apply look as angular velocity times delta once.
+` }];
+}

package/dist/joystick-kit/index.js

@@ -0,0 +1,32 @@
+import { threeJoystickFiles } from './threejs.js';
+import { godotJoystickFiles } from './godot.js';
+import { unityJoystickFiles } from './unity.js';
+import { unrealJoystickFiles } from './unreal.js';
+export const joystickDefaults = { layout: 'dual', deadzone: .15, radius: 72, accent: '#ff681f' };
+/** Radial, continuous, unit-disc axes. Y is up/forward on every target. */
+export function joystickAxis(x, y, deadzone = .15) {
+    if (![x, y, deadzone].every(Number.isFinite) || deadzone < 0 || deadzone >= 1)
+        return { x: 0, y: 0 };
+    const length = Math.hypot(x, y);
+    if (length <= deadzone)
+        return { x: 0, y: 0 };
+    const scale = Math.min(1, (length - deadzone) / (1 - deadzone)) / length;
+    return { x: x * scale, y: y * scale };
+}
+export function createJoystickKit(target, options = {}) {
+    const config = { ...joystickDefaults, ...options };
+    if (!['threejs', 'godot', 'unity', 'unreal', 'all'].includes(target))
+        throw Error('Unknown joystick target.');
+    if (!['move', 'dual'].includes(config.layout) || !Number.isFinite(config.deadzone) || config.deadzone < 0 || config.deadzone > .5 ||
+        !Number.isFinite(config.radius) || config.radius < 32 || config.radius > 160 || !/^#[\da-f]{6}$/i.test(config.accent))
+        throw Error('Invalid joystick configuration.');
+    const targets = target === 'all' ? ['threejs', 'godot', 'unity', 'unreal'] : [target];
+    const factories = { threejs: threeJoystickFiles, godot: godotJoystickFiles, unity: unityJoystickFiles, unreal: unrealJoystickFiles };
+    return {
+        schema: 'gripforge.joystick-kit.v1', module: 'input.joystick', version: '1.0.0', credits: 0, config,
+        conventions: { axes: 'x right, y up/forward', range: 'unit disc; diagonals never exceed magnitude 1', deadzone: 'radial, rescaled continuously outside the dead zone', holding: 'value persists every frame until release/cancel/focus loss', ownership: 'one pointer per stick; movement and look can be held simultaneously', physics: 'Feeds the existing pawn/controller; examples are optional.' },
+        deliveries: targets.map(engine => ({ engine, files: factories[engine](config) })),
+        status: 'files_generated',
+        next: 'Write each delivery file at its relative path, then follow that target README. Install only one movement driver. Generation does not modify your project or claim an in-game verification.',
+    };
+}