@origingame/engine 0.0.0-stage → 0.1.0

package/knowledge/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@origingame/engine-knowledge",
+  "version": "0.1.0",
+  "description": "Origin Engine knowledge for agents: the API wiki generated from api.ogt, the ten og-* skills, the style catalogue and the project scaffold description, laid out for the OriginGame platform's knowledge packs. Not published on its own: @origingame/engine carries it as knowledge/ (docs/release.md §2).",
+  "license": "MIT",
+  "private": true,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fran0220/origin-engine.git",
+    "directory": "packages/knowledge"
+  },
+  "homepage": "https://github.com/fran0220/origin-engine#readme",
+  "bugs": {
+    "url": "https://github.com/fran0220/origin-engine/issues"
+  },
+  "type": "module",
+  "files": [
+    "wiki",
+    "skills",
+    "looks",
+    "scaffold",
+    "rules",
+    "knowledge.json",
+    "scripts",
+    "README.md"
+  ],
+  "scripts": {
+    "prepack": "bun scripts/pack.ts",
+    "validate": "bun scripts/validate.ts",
+    "bundle": "bun scripts/validate.ts --bundle",
+    "test": "bun scripts/validate.ts && bun test ${OG_BUN_TEST_TIMEOUT:+--timeout=$OG_BUN_TEST_TIMEOUT} tests/"
+  }
+}

package/knowledge/rules/platform.json

@@ -0,0 +1,329 @@
+{
+  "schemaVersion": 1,
+  "about": "The OriginGame platform's knowledge rules, transcribed as data so the package validates without a platform checkout. Refresh with `bun scripts/sync-rules.ts <origingame checkout>`.",
+  "payload": {
+    "roots": [
+      "game",
+      "game-scaffold"
+    ],
+    "encoding": "utf-8 (fatal decode, BOM kept)",
+    "regularFilesOnly": true,
+    "source": "packages/game-knowledge/scripts/production-bundle.mjs (readProductionBundle)"
+  },
+  "packs": {
+    "skill": "game/skills/<name>/ -> pack skill:<name>",
+    "scaffold": "game-scaffold/<overlay>/ -> pack scaffold:<overlay>",
+    "instructions": "game/instructions.md -> pack instructions",
+    "other": "any other game/ path -> pack game",
+    "source": "agent-server/src/core/knowledge.ts (packsFromFiles)"
+  },
+  "skills": {
+    "file": "SKILL.md",
+    "frontmatter": {
+      "required": [
+        "name",
+        "description"
+      ],
+      "nameIsDirectory": true
+    },
+    "namePattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+    "existing": [
+      "architecture-discipline",
+      "canvas2d-substrate",
+      "component-forge",
+      "coordinating-game-production",
+      "gameplay-research",
+      "localization",
+      "og-platform",
+      "origin-engine-substrate",
+      "parameter-sweeps",
+      "performance-budget",
+      "playtest-instruments",
+      "producing-game-assets",
+      "recipe-craft",
+      "store-compliance",
+      "threejs-substrate",
+      "vgpu-effects",
+      "visual-acceptance"
+    ],
+    "source": "packages/game-knowledge/production/game/skills/*/SKILL.md (every skill's front matter: name equals its directory); agent-server/src/core/knowledge.ts (frontMatterDescription: the runner reads description)"
+  },
+  "tools": {
+    "snake": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$",
+    "notTools": [
+      "text_server_adv"
+    ],
+    "retired": [
+      "codemode"
+    ],
+    "known": [
+      "Task",
+      "account_usage",
+      "action_id",
+      "action_ids",
+      "ai_model",
+      "aigcc_begin",
+      "aigcc_bind_release",
+      "aigcc_confirm_cover",
+      "aigcc_generate_cover",
+      "aigcc_prepare_upload",
+      "aigcc_publish",
+      "aigcc_status",
+      "analytics_agent_reliability",
+      "analytics_compare_game_versions",
+      "analytics_compare_workflow_cohorts",
+      "analytics_event_evidence",
+      "analytics_failure_clusters",
+      "analytics_game_funnel",
+      "analytics_project_runs",
+      "analytics_run_summary",
+      "analytics_run_timeline",
+      "analytics_trace_details",
+      "animate_in_place",
+      "apply_patch",
+      "apply_tunables",
+      "archive_base64",
+      "artifact_fetch",
+      "ask_user",
+      "aspect_ratio",
+      "asset_optimize",
+      "asset_process",
+      "assets_detail",
+      "assets_download",
+      "assets_fetch_plan",
+      "assets_list_files",
+      "assets_search",
+      "assets_search_3d",
+      "assets_search_audio",
+      "assets_search_fonts",
+      "assets_search_hdr",
+      "assets_search_images",
+      "assets_used",
+      "budget_report",
+      "catalog_changed",
+      "change_fps",
+      "channel_list",
+      "character_create",
+      "character_dispute",
+      "character_get",
+      "character_id",
+      "character_list",
+      "character_media_delete",
+      "character_media_upload",
+      "character_update",
+      "checkpoint_id",
+      "code_exec",
+      "collection_get",
+      "concept_compare",
+      "content_not_ready",
+      "core_loop",
+      "cover_url",
+      "create_thread",
+      "deliver",
+      "deploy_activate",
+      "deploy_create",
+      "deploy_delete",
+      "deploy_discard_release",
+      "deploy_generate_artwork",
+      "deploy_list",
+      "deploy_prepare_upload",
+      "deploy_releases",
+      "deploy_status",
+      "deploy_update",
+      "deploy_update_metadata",
+      "design_note",
+      "discussion_categories",
+      "discussion_delete",
+      "discussion_me",
+      "discussion_post",
+      "discussion_reply",
+      "discussion_status",
+      "discussion_vote",
+      "docs",
+      "download_thread_changes",
+      "download_thread_file",
+      "duration_seconds",
+      "edit_design_graph",
+      "edit_file",
+      "edit_image",
+      "enable_original_uv",
+      "enable_pbr",
+      "engine_capture",
+      "engine_export",
+      "engine_probe",
+      "engine_reload",
+      "engine_scaffold",
+      "engine_start",
+      "engine_stop",
+      "engine_sweep",
+      "error_code",
+      "error_stage",
+      "execute",
+      "expected_revision",
+      "expires_at",
+      "export_with_geometry",
+      "extract_armature",
+      "feel_compare",
+      "find_thread",
+      "flow_map",
+      "game_comments_list",
+      "game_comments_moderate",
+      "game_id",
+      "game_leaderboard_inspect",
+      "game_leaderboard_reset",
+      "game_lineage",
+      "game_remix",
+      "game_reports_list",
+      "game_saves_inspect",
+      "gameplay_get",
+      "gameplay_search",
+      "generate_3d",
+      "generate_apply_motions",
+      "generate_audio",
+      "generate_balance",
+      "generate_complete_upload",
+      "generate_download",
+      "generate_get_tasks",
+      "generate_image",
+      "generate_meshy_artifacts",
+      "generate_meshy_library",
+      "generate_motion",
+      "generate_motion_artifacts",
+      "generate_motion_library",
+      "generate_music",
+      "generate_prepare_upload",
+      "generate_sfx",
+      "generate_speech",
+      "generate_speech_voices",
+      "generate_tripo_3d",
+      "generate_video",
+      "generate_wait_tasks",
+      "genre_browse",
+      "get_thread_status",
+      "glob",
+      "grep",
+      "height_meters",
+      "idempotency_key",
+      "image_cutout",
+      "image_url",
+      "in_progress",
+      "include_artwork",
+      "include_content",
+      "input_hints",
+      "input_reference",
+      "insufficient_scope",
+      "invalid_input",
+      "land_changes",
+      "last_frame",
+      "level_report",
+      "license_id",
+      "list_directory",
+      "main",
+      "media_id",
+      "media_persistence",
+      "media_url",
+      "mime_type",
+      "model_type",
+      "motion_task_id",
+      "node_modules",
+      "not_found",
+      "operation_id",
+      "oracle",
+      "outcome_unknown",
+      "payment_required",
+      "platform_ai",
+      "platform_channel",
+      "player_id",
+      "playtest",
+      "pose_mode",
+      "post_process",
+      "poster_url",
+      "precondition_required",
+      "prepare_production",
+      "rate_limited",
+      "read_bytes",
+      "read_design_graph",
+      "read_file",
+      "read_thread",
+      "reference_audios",
+      "reference_images",
+      "reference_videos",
+      "registry_get",
+      "registry_list",
+      "registry_search",
+      "release_id",
+      "remix_policy",
+      "remix_royalty_bps",
+      "request_secret",
+      "resource_metadata",
+      "response_format",
+      "review_playtest",
+      "rig_check",
+      "sample_rate",
+      "sdk_scaffold",
+      "search",
+      "send_thread_message",
+      "set_goal",
+      "shell",
+      "shell_kill",
+      "shell_status",
+      "should_remesh",
+      "should_texture",
+      "size_bytes",
+      "skill",
+      "source_checkpoint",
+      "stage_capture",
+      "stage_record",
+      "stage_show",
+      "sub_category",
+      "submission_unknown",
+      "system_module",
+      "target_polycount",
+      "task_id",
+      "text_preview",
+      "text_refine",
+      "text_to_motion",
+      "texture_resolution",
+      "timeout_seconds",
+      "too_large",
+      "tool_search",
+      "undo_edit",
+      "universe_search",
+      "update_annotation",
+      "update_plan",
+      "upload_id",
+      "upload_thread_file",
+      "upstream_unavailable",
+      "user_key",
+      "verify_milestone",
+      "wait_for_threads",
+      "write_file"
+    ],
+    "source": "packages/game-knowledge/scripts/production.test.mjs (toolInventory and 'Game instructions and skills name only tools a Session can be offered'): production/game/instructions.md ## Tools plus packages/origin-mcp/docs/*.md"
+  },
+  "scaffold": {
+    "pinFile": "origin-engine.json",
+    "pin": {
+      "schema": 1,
+      "probe": {
+        "protocol": 5,
+        "wire": 1
+      }
+    },
+    "distributionFile": "distribution.json",
+    "distributionEntry": [
+      "path",
+      "bytes",
+      "sha256",
+      "licence",
+      "source"
+    ],
+    "existingOverlays": [
+      "canvas2d",
+      "origin-engine",
+      "shared",
+      "three"
+    ],
+    "source": "packages/game-knowledge/production/game-scaffold/origin-engine/{origin-engine.json,distribution.json}; scripts/production.test.mjs asserts pin.distribution and pin.probe.protocol 5; production/README.md: the payload is UTF-8 text only, binary files are named with digests in distribution.json"
+  }
+}

package/knowledge/scaffold/README.md

@@ -0,0 +1,27 @@
+# The Origin Engine scaffold
+
+What `npm create @origingame/game` (`@origingame/create-game`) produces: a copy
+of the engine repository's `templates/game/` with the project's `name` and
+`id` filled in. The platform mounts it as the scaffold overlay
+`game-scaffold/origin-engine-ts/` (`knowledge.json`); it stands alone, never
+on top of the Web scaffold's `shared/`.
+
+| Path | Role |
+|---|---|
+| `project.ogt` | The manifest every `og` command reads: `name`, `id`, `engine` (the pinned `@origingame/engine` version), `entry`, `profile` (`"2d"` or `"3d"`), `tick`, `seed`, `scenes` (name to scene path under `assets/`), `scene` (the first one) and `publish` (`probe player`: a publish build keeps only the player-facing probe members; `out` the build directory) |
+| `src/main.ts` | The game entry: components, systems and `export default og.game({...})`, starting from the design's hello world and loading `scenes/main.ogt` |
+| `package.json` | `@origingame/engine` pinned to the same version as `project.ogt`; scripts `dev`, `start`, `build`, `publish-build`, `cook`, `test` calling `og` |
+| `tsconfig.json` | Strict TypeScript over `src/` and `tests/` |
+| `tests/smoke.og.ts` | The first playtest `og test` runs headless through `og run --commands` |
+| `assets/` | Source assets with their import settings and licences: `scenes/main.ogt`, the game's look `looks/<id>.ogt` (extending a catalogue preset; `GameDesc.look` names it, og-taste §12), two glTF models, two textures (one normal map), a sound and a CJK-subset font |
+| `LICENSES.md` | One row per asset: licence and origin |
+| `.gitignore` | `cooked/`, `dist/` and `node_modules/` are build output |
+| `.gitattributes` | Media (models, textures, audio, fonts) through Git LFS; `.ogt` and `.ts` text with LF endings. The template stores it as `gitattributes`, renamed by the scaffolder and the mount, because the engine repository keeps the template's media as plain blobs |
+
+`origin-engine.json` pins the engine package and version, the template and
+the probe protocol (5, wire 1). `distribution.json` names every binary file
+(models, textures, audio, fonts) with its size, SHA-256 and licence, because
+the platform's knowledge payload is UTF-8 text only; the scaffolder copies
+binaries from the published template and checks the digests.
+`bun scripts/scaffold.ts --write` regenerates it after a deliberate asset
+change, and `bun run test` fails while it is stale.

package/knowledge/scaffold/distribution.json

@@ -0,0 +1,48 @@
+{
+  "schema": 1,
+  "about": "Binary files of the Origin Engine project template that a scaffolded Game needs but that are not knowledge text. The scaffolder copies them from the published template (@origingame/create-game) and verifies each digest.",
+  "files": [
+    {
+      "path": "assets/audio/blip.wav",
+      "bytes": 44144,
+      "sha256": "4fe30d6e883337c7d3c99f2cf0e3f2b1ca80c742587479fd878cb719580acaea",
+      "licence": "CC0 1.0 (LICENSES.md)",
+      "source": "templates/game/assets/audio/blip.wav of origingame/origin-engine; shipped in @origingame/create-game's template/"
+    },
+    {
+      "path": "assets/fonts/NotoSansSC-Regular-subset.ttf",
+      "bytes": 2513672,
+      "sha256": "9235b106a17bed31a2b28acc6deccb3d45a6aa02848c96fd2cc1d8540211a1e6",
+      "licence": "SIL Open Font License 1.1 (`assets/fonts/OFL.txt`) (LICENSES.md)",
+      "source": "templates/game/assets/fonts/NotoSansSC-Regular-subset.ttf of origingame/origin-engine; shipped in @origingame/create-game's template/"
+    },
+    {
+      "path": "assets/models/dropship.glb",
+      "bytes": 562864,
+      "sha256": "c7bf4c177bf360bc65b66d8636c1d8cf063cb65209505cf9f8e0e21461ec9c54",
+      "licence": "MIT (copyright 2026 Leichtbier) (LICENSES.md)",
+      "source": "templates/game/assets/models/dropship.glb of origingame/origin-engine; shipped in @origingame/create-game's template/"
+    },
+    {
+      "path": "assets/models/walker.glb",
+      "bytes": 34296,
+      "sha256": "e068aeca18b491e54b48ae8c264d208a414f9de455a571340bf55ef0c3d2face",
+      "licence": "CC0 1.0 (LICENSES.md)",
+      "source": "templates/game/assets/models/walker.glb of origingame/origin-engine; shipped in @origingame/create-game's template/"
+    },
+    {
+      "path": "assets/textures/stone.png",
+      "bytes": 112774,
+      "sha256": "8622957415b5174f09a2564256d319c14692998b3f7fd1ac6ae9d3709ed71a9c",
+      "licence": "CC0 1.0 (LICENSES.md)",
+      "source": "templates/game/assets/textures/stone.png of origingame/origin-engine; shipped in @origingame/create-game's template/"
+    },
+    {
+      "path": "assets/textures/stone_n.png",
+      "bytes": 212633,
+      "sha256": "c3bfb1778ace9010f8da8f3ea8664e68cddf446776a2dff7bdcf11f31bb22dcb",
+      "licence": "CC0 1.0 (LICENSES.md)",
+      "source": "templates/game/assets/textures/stone_n.png of origingame/origin-engine; shipped in @origingame/create-game's template/"
+    }
+  ]
+}

package/knowledge/scaffold/origin-engine.json

@@ -0,0 +1,19 @@
+{
+  "schema": 1,
+  "distribution": "origin-engine",
+  "substrate": "origin-engine-ts",
+  "engine": {
+    "package": "@origingame/engine",
+    "version": "0.1.0",
+    "repository": "origingame/origin-engine"
+  },
+  "template": {
+    "source": "templates/game",
+    "create": "@origingame/create-game",
+    "version": "0.1.0"
+  },
+  "probe": {
+    "protocol": 5,
+    "wire": 1
+  }
+}

package/knowledge/scaffold/template/.origin/setup

@@ -0,0 +1,14 @@
+#!/bin/sh
+# Prepares this Game's cloud sandbox snapshot: Origin runs it once per
+# snapshot build, in the checkout, without a terminal, for at most 20 minutes,
+# and saves the result for new sandboxes of the Game. Keep it idempotent; it
+# never receives credentials. Only ignored output is kept: node_modules/ and
+# cooked/ (og cook is incremental, so a new sandbox starts cooked).
+set -eu
+if [ -f bun.lock ]; then bun install --frozen-lockfile; else bun install; fi
+og="${ORIGIN_OG_BIN:-og}"
+if ! command -v "$og" >/dev/null 2>&1; then
+  echo "no og on this executor class; the first og run cooks instead"
+  exit 0
+fi
+"$og" cook .

package/knowledge/scaffold/template/LICENSES.md

@@ -0,0 +1,23 @@
+# Template asset licences
+
+Every binary the template ships, with its licence; `@origingame/create-game`
+carries this file into each scaffolded project.
+
+| File | Licence | Origin |
+|---|---|---|
+| `assets/models/dropship.glb` | MIT (copyright 2026 Leichtbier) | the `core-business` example of OriginGame's `origingame-examples` repository (`examples/core-business/assets/dropship.glb`, generated by its `dropship.py`); its `LICENSE` is MIT. Also a test model of the engine (`crates/og-tests/assets/`) |
+| `assets/models/walker.glb` | CC0 1.0 | self-made by the Origin Engine authors: a 13-node skinned walker of boxes with two morph targets and six clips (LINEAR, STEP, CUBICSPLINE, weights; footstep markers in `extras."og.events"`), generated by `crates/og-anim/tools/make_rig.py` (deterministic). The scene's `trickster` and the guard are both instances of it |
+| `assets/textures/stone.png`, `assets/textures/stone_n.png` | CC0 1.0 | self-made by the Origin Engine authors: procedural value-noise tiles and the normal map of the same height field, generated by `templates/tools/make-template-assets.py` |
+| `assets/audio/blip.wav` | CC0 1.0 | self-made: a 0.5 s rising sine pickup sound, same script |
+| `assets/audio/click.ogt` | CC0 1.0 | og-cook's `click` sound preset (`og sfx click`), synthesised at cook time |
+| `assets/fonts/NotoSansSC-Regular-subset.ttf` | SIL Open Font License 1.1 (`assets/fonts/OFL.txt`) | the OriginGame platform's project-template font: Noto Sans SC Regular subset to Latin, punctuation, kana, full-width forms and GB2312 by the platform's `engine/scripts/subset-font.py` |
+
+## Provenance note
+
+Until 2026-10-22 the `trickster` entity was `trickster.glb`, a model copied
+from the `edg-king-match` example of `origingame-examples`, which declares
+no licence (that repository grants none for the collection); the public
+template ships nothing whose licence is not named (docs/release.md §4 R6),
+so the entity is the walker now. The engine's own test copy stays in
+`crates/og-tests/assets/` and in `templates/fx-showcase`, which no package
+ships.

package/knowledge/scaffold/template/README.md

@@ -0,0 +1,37 @@
+# The game template
+
+What `npm create @origingame/game` writes: the smallest whole Origin Engine
+project, and the hello of the engine's design grown into a scene. A menu's
+Start button (or S, or Enter) spins the trickster and drops a crate onto
+the ground; a guard patrols the yard, sees only inside its cone and not
+through the wall, raises the alarm, chases, searches and goes back.
+
+```sh
+og run .     # headless with the probe; og dev . reloads on save
+og test .    # tests/smoke.og.ts and tests/guard.og.ts
+og polish .  # the taste and feel scores of those playtests
+og build .   # the play page
+```
+
+## What it demonstrates, and the skills it exercises
+
+| Part | Where | Skill |
+|---|---|---|
+| The project: `project.ogt`, the entry's `og.game` default export, `cooked/` from `assets/` | `project.ogt`, `src/main.ts` | og-game §2, §5 |
+| Components, a resource, systems over archetype columns, one job each | `Health`, `Velocity`, `Spin`, `Run`; `Move`, `StartSpin`, `Drop`, `Rotate` | og-core §4, §5; og-game §3 |
+| The frame's art direction as data: a look extending a catalogue preset, applied by `GameDesc.look` | `assets/looks/origin-game.ogt` (a created game's is `<id>.ogt`), `og.game({ look })` | og-taste §1, §12 |
+| A text scene spawned before the first tick, a glTF model, a font, a box with a collider that falls | `assets/scenes/main.ogt`, `start` | og-game §4, §6, §13 |
+| A menu panel whose button answers with a look and a sound (og sfx's click preset) | `Menu`, `assets/audio/click.ogt` | og-ui §1, §3; og-taste §6; og-audio §2, §3 |
+| Every word the menu shows from a string table, the base one in the source language | `assets/strings/en.ogt`, `Menu` | og-i18n §1, §2 |
+| A guard as data: a state machine on og.ai, a navmesh cooked from the yard, sight cones against the wall | `assets/ai/guard.ogt`, `assets/nav/yard.ogt` | og-ai §1–§5 |
+| Commands with their usage in `help`, facts for playtests | `commands`, `commandHelp`, `facts` | og-game §3; og-build §1 |
+| Playtests that assert on dumps and facts, never on the code | `tests/` | og-build §3, §4 |
+
+`og polish .` (2026-10-19): taste 100, feel 87 (tests/evidence/E7/polish/
+in the engine repository). The feel row below 90 is idle frames: the guard
+playtest stages its scenario without pressing Start, so for half its ticks
+only the guard stands still at a corner of its search, and the smoke
+playtest waits half a second on the title before its press. A game made
+from the template should keep a playtest that plays it.
+
+Asset licences: `LICENSES.md`.

package/knowledge/scaffold/template/assets/ai/guard.ogt

@@ -0,0 +1,48 @@
+type behaviour
+version 1
+---
+# The guard's state machine (og.ai; every node is in the og-ai skill). It
+# patrols its post until it sees the trickster in its view cone, raises the
+# alarm (the game's `alarm` command) and chases; when it loses sight it
+# searches where it last saw it for 3 seconds, then goes back to its post.
+name "guard"
+route post {
+  point -6 0 -3
+  point -6 0 4
+  point -1 0 6
+}
+machine {
+  initial patrol
+  state patrol {
+    patrol post {
+      wait 1
+      speed 1.5
+    }
+    to alert {
+      check sees
+    }
+  }
+  state alert {
+    enter {
+      command alarm
+    }
+    chase {
+      speed 3
+      reach 1.5
+    }
+    to search {
+      check sees is false
+    }
+  }
+  state search {
+    move_to lastSeen {
+      speed 2
+    }
+    to alert {
+      check sees
+    }
+    to patrol {
+      after 3
+    }
+  }
+}

package/knowledge/scaffold/template/assets/audio/click.ogt

@@ -0,0 +1,9 @@
+type sfx
+version 1
+---
+# a tiny UI tick: og.load.sound(world, "<this file>") plays it.
+preset "click"
+seed 0
+pitch 1
+length 1
+volume 1

package/knowledge/scaffold/template/assets/fonts/NotoSansSC-Regular-subset.ttf.ogt

@@ -0,0 +1,12 @@
+type import
+version 1
+---
+# The atlas covers Latin-1, CJK punctuation and the strings the template shows.
+# `charset all` cooks every glyph of the platform subset (GB2312 + kana): see
+# crates/og-cook/README.md for its size and time.
+font {
+  charset latin cjk-punct
+  chars "开始游戏设置退出暂停继续分数最高关卡生命时间胜利失败加载中"
+  em_px 32
+  px_range 4
+}