@opengroundplan/core 0.1.1

package/catalog/sources/game-3d.yaml

@@ -0,0 +1,834 @@
+# game-3d.yaml
+#
+# Groundplan template source catalog — category: game-3d
+# Research date: 2026-07-18
+#
+# VERIFICATION NOTES
+#   Every `stars`, `lastCommit`, `spdx` and archived-status value below was read
+#   from a GitHub primary source on 2026-07-18. Nothing here comes from memory,
+#   a blog post, or a README badge.
+#
+#   The unauthenticated GitHub REST API quota (60/hr) was already exhausted when
+#   this research began, so verification used the other primary path on
+#   github.com itself — the same data, different transport:
+#     stars      — `aria-label="N users starred this repository"` on the repo page
+#     spdx       — GitHub's own license-detection label in the repo sidebar
+#                  (the identical detector that populates `license.spdx_id`)
+#     lastCommit — `<updated>` of the newest entry in
+#                  https://github.com/{owner}/{repo}/commits/{defaultBranch}.atom
+#     archived   — presence of the "Public archive" banner (zero hits on all
+#                  entries below; none of these repos is archived)
+#   `spdxSource: LICENSE-file` marks entries where GitHub's sidebar label was
+#   absent or incomplete and the raw LICENSE text was read directly to resolve it.
+#
+#   ADVERSARIAL RE-VERIFICATION PASS (2026-07-18, independent second reader)
+#   All 17 retained entries plus all 5 droppedCandidates and all 11 held-back
+#   candidates were re-fetched from scratch. Result: every license, every star
+#   count, every lastCommit and every URL held up. Zero license mismatches, zero
+#   404s, zero archived repos, zero stale entries mislabelled maintained. The
+#   licence gate on this file is sound.
+#   The re-pass did correct five factual errors in the prose, none license-related:
+#     - phaserjs/template-vite-ts: scenes are at `src/game/scenes/` (not
+#       `src/scenes/`) and the config is `src/game/main.ts`; there are five
+#       scenes, not four; the claimed `scale.mode`/`autoCenter: CENTER_BOTH`
+#       does not exist in the config at all — that gap moved to whatToAvoid.
+#     - create-colyseus-app: variants are cjs/esm/haxe/monorepo/typescript, not
+#       the "typescript, javascript, bun, haxe" originally listed.
+#     - pmndrs/ecctrl: repo was restructured into per-concern modules; the three
+#       cited paths (`src/Ecctrl.tsx`, `src/stores/useGame.ts`,
+#       `EcctrlAnimation.tsx`) no longer exist and were repointed.
+#     - bevy_new_2d: `src/audio` is a single `audio.rs` file, not a directory.
+#     - bevy_new_2d: it is tri-licensed MIT OR Apache-2.0 OR CC0-1.0; GitHub's
+#       sidebar surfaces only "MIT", so the recorded spdx was incomplete.
+#       Still vendorable under any of the three — not a gate failure.
+#   Re-verified independently against LICENSE text (not just the sidebar label):
+#   pmndrs/xr (verbatim MIT, (c) 2024 Bela Bohlender), both Unity Companion
+#   License repos, bevy_new_2d's three LICENSE files, and ecctrl's NOTICE
+#   (which confirms MIT and flags its example animations as CC0/Quaternius).
+#
+#   Because lastCommit is the newest commit timestamp rather than the API's
+#   `pushed_at`, the two can differ by seconds; that has no bearing on staleness.
+#
+#   NOT-DETECTED IS NEVER TREATED AS PERMISSIVE. Three repos returned no license
+#   label and were resolved by reading the file. They landed in two very
+#   different places: pmndrs/xr is verbatim MIT (vendorable), while both
+#   Unity-Technologies repos are the Unity Companion License — a proprietary,
+#   Unity-dependent-only license with no SPDX id. Both were dropped as excluded.
+#
+#   licenseClass gate:
+#     vendorable     — MIT, Apache-2.0, BSD-2/3, ISC, Unlicense, CC0, 0BSD.
+#                      Copy + adapt permitted. Apache-2.0 and BSD require the
+#                      copyright/NOTICE text to travel with any copied file.
+#     reference-only — MPL-2.0, LGPL, EPL. Read for ideas; do not copy files.
+#     excluded       — GPL, AGPL, SSPL, BUSL, source-available, or unlicensed.
+#
+#   `maintained: false` is set when the last commit is >18 months old (i.e.
+#   before 2025-01-18), regardless of star count. Every entry retained below was
+#   committed to within the last 9 months. Two well-known starters failed this
+#   test and were dropped rather than listed — see droppedCandidates at the foot
+#   of this file.
+#
+#   CATEGORY-SPECIFIC LICENSE WARNING. Game engines are the worst category in
+#   this catalog for license traps, and the trap is asymmetric: the *engines*
+#   are permissive but much of the *sample and template* content is not.
+#   Unity ships its first-party netcode and its flagship Boss Room sample under
+#   the Unity Companion License, which permits use only in Unity-dependent
+#   projects — unusable as Groundplan source material. Godot and Bevy have no such
+#   problem. Where a first-party option was excluded, a permissive third-party
+#   equivalent was substituted (Mirror in place of Unity Netcode).
+
+category: game-3d
+
+sources:
+
+  # ---------------------------------------------------------------- simple ---
+
+  - name: phaserjs/template-vite-ts
+    url: https://github.com/phaserjs/template-vite-ts
+    stars: 188
+    spdx: MIT
+    spdxSource: github-license-detection
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-04-21T08:31:28Z"
+    stack: typescript, phaser, vite
+    complexity: simple
+    proposedLayerIds:
+      - engine-phaser
+      - build-vite-ts
+      - game-scene-router
+      - assets-static-pipeline
+    whatToBorrow: >-
+      The official Phaser starter and the cleanest strip-down baseline in the
+      whole category — roughly a dozen files, no framework noise. Take
+      `src/game/main.ts` (the `Phaser.Types.Core.GameConfig` object: type
+      `AUTO`, fixed 1024x768 canvas, `parent: 'game-container'`, and the scene
+      array) and the `src/game/scenes/` set —
+      Boot -> Preloader -> MainMenu -> Game -> GameOver — which is the
+      scene-lifecycle convention nearly every Phaser project ends up
+      rediscovering: Boot loads
+      only the assets needed to draw the loading bar, Preloader loads the rest
+      and shows progress via `this.load.on('progress')`. Also worth adapting is
+      `vite/config.dev.mjs` vs `vite/config.prod.mjs` — the prod config's manual
+      `phaser` vendor chunk plus terser passes is the difference between a 1.5MB
+      and a cached-vendor bundle. The `public/assets` convention keeps game art
+      out of the bundler graph entirely.
+    whatToAvoid: >-
+      There is no state management, no save system, no audio layer and no test
+      setup — this is a canvas and a scene stack, nothing more. Note the config
+      ships NO `scale` block at all: the canvas is a fixed 1024x768 and does not
+      respond to viewport size, so any responsive template must add
+      `scale.mode` / `autoCenter` itself. The template
+      posts anonymous usage telemetry from `log.js` on build; strip that before
+      vendoring. Star count is low because it is a template repo people click
+      "Use this template" on rather than star, so do not read 188 as weak
+      adoption — read the 40k-star parent engine instead.
+
+  - name: colyseus/create-colyseus-app
+    url: https://github.com/colyseus/create-colyseus-app
+    stars: 39
+    spdx: MIT
+    spdxSource: github-license-detection
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-04-06T14:20:33Z"
+    stack: typescript, node, colyseus
+    complexity: simple
+    proposedLayerIds:
+      - netcode-colyseus
+      - server-node-express
+      - build-tsx-watch
+      - test-colyseus-room
+    whatToBorrow: >-
+      The canonical minimal authoritative-server scaffold, and the single best
+      shape to copy for any "multiplayer room" Groundplan layer. Take
+      `templates/typescript/src/rooms/MyRoom.ts` (the `Room<MyRoomState>`
+      subclass with `onCreate`/`onJoin`/`onLeave`/`onDispose` and
+      `this.onMessage("type", cb)` routing) and
+      `src/rooms/schema/MyRoomState.ts`, which demonstrates the `@type("string")`
+      / `MapSchema` decorator pattern that drives Colyseus's binary delta
+      encoding — getting this file's shape right is 80% of a working multiplayer
+      game. `src/app.config.ts` is the modern entry point worth adapting: it
+      wires `gameServer.define("my_room", MyRoom)`, mounts the monitor at
+      `/monitor` and the playground in dev only. `test/MyRoom.test.ts` shows
+      `boot()` + `sdk.joinOrCreate()` + `waitForNextPatch()`, which is the only
+      sane way to integration-test room state sync.
+    whatToAvoid: >-
+      Single room, no auth, no persistence, no matchmaking beyond
+      `joinOrCreate`, and the monitor endpoint is unauthenticated — all three
+      must be closed before anything ships. The repo carries five variants under
+      `templates/` (cjs, esm, haxe, monorepo, typescript); vendor only the
+      `typescript` one — it is the variant the paths above refer to. 39 stars is a
+      scaffolding CLI, not a project — judge it by the 7k-star server it emits.
+
+  - name: pmndrs/ecctrl
+    url: https://github.com/pmndrs/ecctrl
+    stars: 762
+    spdx: MIT
+    spdxSource: github-license-detection
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-06-15T05:29:04Z"
+    stack: typescript, react, three, r3f, rapier
+    complexity: simple
+    proposedLayerIds:
+      - controls-character-ecctrl
+      - physics-rapier
+      - input-keyboard-gamepad
+      - camera-third-person
+    whatToBorrow: >-
+      A single-concern library that solves the one problem every 3D project hits
+      on day two: a character controller that does not feel bad. Borrow the
+      floating-capsule approach in `src/character/Ecctrl.tsx` — a ray-cast down
+      from a rigid body with a spring/damper (`springK = 80`, `dampingC = 6`)
+      holding the body at `floatHeight = 0.2` instead of a collider resting on
+      the ground, which is what eliminates stair-stepping jitter and slope
+      sliding (see the `floatingForce` computation via `subVectors`). Also adapt
+      `src/character/animation/useEcctrlAnimationStore.ts` (a compact zustand
+      store for animation state transitions) and
+      `EcctrlAnimationStateController.tsx` plus `resolveAnimationState.ts`, which
+      map controller velocity to GLTF animation clip names — a clean example of
+      decoupling physics state from the animation mixer. `src/input/Joystick.tsx`
+      and `src/input/VirtualButton.tsx` are a usable mobile touch input layer.
+    whatToAvoid: >-
+      Tightly bound to @react-three/rapier and to R3F — none of it transfers to
+      vanilla Three.js or Babylon without a rewrite, so scope this to R3F layers
+      only. The tuning surface is enormous (30+ props) and the defaults are
+      tuned for a specific character scale; expect to re-tune rather than accept
+      defaults. Documentation is largely example-driven, so read the source over
+      the README. The repo has been restructured into per-concern modules
+      (`character/`, `camera.ts`, `animation`, `input/`, `gravity/`, `vehicles/`)
+      and the joystick is now exported as `Joystick`, not `EcctrlJoystick` — most
+      tutorials and older docs still cite the flat `src/Ecctrl.tsx` /
+      `EcctrlJoystick` layout, which no longer exists. Check `src/index.ts` for
+      the real public surface before wiring imports.
+
+  # -------------------------------------------------------------- standard ---
+
+  - name: pmndrs/react-three-fiber
+    url: https://github.com/pmndrs/react-three-fiber
+    stars: 31462
+    spdx: MIT
+    spdxSource: github-license-detection
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-05-06T20:19:24Z"
+    stack: typescript, react, three
+    complexity: standard
+    proposedLayerIds:
+      - render-r3f
+      - render-threejs
+      - build-vite-ts
+      - build-nextjs
+      - state-zustand
+    whatToBorrow: >-
+      The default 3D stack for anyone already in React, and the reconciler most
+      of this category's other entries orbit. The value for Groundplan is less the
+      library source than the integration patterns: adapt the `<Canvas>`
+      configuration conventions (the `gl` prop for renderer settings,
+      `camera={{ position, fov }}`, `dpr={[1, 2]}` for retina clamping, and
+      `frameloop="demand"` which is the single highest-leverage setting for any
+      non-continuously-animated scene). Take `useFrame` for the render loop and
+      `useThree` for imperative escape hatches, and copy the `extend()` mechanism
+      for registering non-core Three.js classes as JSX elements — that is how any
+      custom shader or third-party Three addon gets a declarative API. The
+      `examples/` directory carries current Vite and Next.js wiring, including
+      the SSR-safe dynamic-import pattern Next needs.
+    whatToAvoid: >-
+      This is a renderer, not a game framework — no physics, no asset pipeline,
+      no input handling, no audio; all of that arrives as separate pmndrs
+      packages, so a realistic template pulls 5-8 dependencies from one org and
+      inherits that org's release cadence. React reconciliation is a real cost in
+      hot loops: mutate refs inside `useFrame` rather than calling `setState`
+      per frame, and treat any per-frame `setState` in vendored example code as a
+      bug to fix. Version coupling between r3f, drei and three is tight enough
+      that a template must pin all three together.
+
+  - name: pmndrs/drei
+    url: https://github.com/pmndrs/drei
+    stars: 9748
+    spdx: MIT
+    spdxSource: github-license-detection
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-01-30T16:53:55Z"
+    stack: typescript, react, three, r3f
+    complexity: standard
+    proposedLayerIds:
+      - render-r3f
+      - controls-orbit
+      - assets-gltf-loader
+      - lighting-environment-hdri
+      - perf-instancing
+    whatToBorrow: >-
+      The helper library that turns bare R3F into something you can ship, and the
+      richest single source of copyable 3D patterns in the ecosystem. Highest
+      value for Groundplan layers: `<Environment preset="..." />` for one-line IBL
+      lighting (which is what makes hobby scenes suddenly look professional),
+      `<OrbitControls>` / `<CameraControls>` for camera layers, `useGLTF` with
+      its `.preload()` static for the asset layer, `<Instances>`/`<Merged>` for
+      the draw-call-reduction layer, and `<Html>` for DOM-in-3D overlays. Also
+      adapt `<AdaptiveDpr>` and `<PerformanceMonitor>`, which together implement
+      dynamic resolution scaling — the standard answer to "runs badly on
+      laptops". `<Bvh>` is worth taking for any scene doing raycast picking
+      against dense geometry.
+    whatToAvoid: >-
+      Enormous surface area (150+ components) and a grab-bag character — import
+      selectively from `@react-three/drei` subpaths or the bundle balloons.
+      Several components are thin wrappers whose abstraction leaks the moment you
+      need a Three.js API they did not forward; when that happens drop to
+      three.js directly rather than fighting the wrapper. Some components are
+      effectively unmaintained experiments sitting beside heavily-used ones with
+      no signal distinguishing them, so verify any component you vendor is
+      actually exercised in the repo's own examples.
+
+  - name: pmndrs/react-three-rapier
+    url: https://github.com/pmndrs/react-three-rapier
+    stars: 1412
+    spdx: MIT
+    spdxSource: github-license-detection
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2025-11-03T00:38:25Z"
+    stack: typescript, react, three, r3f, rapier, wasm
+    complexity: standard
+    proposedLayerIds:
+      - physics-rapier
+      - render-r3f
+      - collision-events
+      - debug-physics-overlay
+    whatToBorrow: >-
+      The physics layer for R3F, and a good template for wrapping any WASM
+      simulation in React. Take the `<Physics>` provider configuration
+      (`gravity`, `timeStep="vary"` vs a fixed step, `interpolate`, and `paused`
+      — a fixed timestep with interpolation is the correct default for
+      determinism and Groundplan templates should ship it that way), plus the
+      `<RigidBody>` / `<CuboidCollider>` composition model. The `colliders="hull"
+      | "trimesh" | "ball"` auto-generation prop is worth adapting wholesale:
+      it derives colliders from mesh geometry so authors do not hand-write
+      collision shapes. Copy the collision-event surface (`onCollisionEnter`,
+      `onIntersectionEnter`, and sensor colliders) as the gameplay-trigger
+      pattern, and keep the `debug` prop wiring — a toggleable collider overlay
+      pays for itself immediately.
+    whatToAvoid: >-
+      Rapier ships as WASM, which means bundler configuration is a real
+      integration cost — Vite needs `optimizeDeps.exclude` and Next.js needs
+      `webpack.experiments.asyncWebAssembly`; any vendored template must carry
+      that config or it fails at build time, not runtime. Trimesh colliders are
+      slow and cannot be dynamic; templates should default to hull. At ~9 months
+      since the last commit this is the least active entry retained here — still
+      comfortably inside the 18-month bar, but track it, as the underlying
+      dimforge/rapier moves faster than the wrapper.
+
+  - name: pmndrs/xr
+    url: https://github.com/pmndrs/xr
+    stars: 2600
+    spdx: MIT
+    spdxSource: LICENSE-file   # GitHub detected no license; LICENSE is verbatim MIT ("Permission is hereby granted, free of charge...") (c) 2024 Bela Bohlender
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-05-29T01:42:21Z"
+    stack: typescript, react, three, r3f, webxr
+    complexity: standard
+    proposedLayerIds:
+      - xr-webxr
+      - render-r3f
+      - input-hand-tracking
+      - ui-spatial
+    whatToBorrow: >-
+      The current WebXR layer for R3F (v6, a full rewrite of the older react-xr)
+      and the only maintained permissive option for VR/AR templates. Adapt the
+      `createXRStore()` + `<XR store={store}>` pattern — decoupling the XR session
+      store from the component tree is what lets non-XR UI trigger
+      `store.enterVR()`. Take the controller/hand model components and the
+      `<XROrigin>` rig for player positioning, and the pointer abstraction that
+      unifies ray, grab and touch input so gameplay code does not branch on input
+      source. The `examples/` directory carries working hand-tracking and
+      AR-passthrough setups that are otherwise painful to assemble from spec
+      documents.
+    whatToAvoid: >-
+      GitHub's license detector returns nothing for this repo because the LICENSE
+      file leads with a copyright line — do not let an automated scan mark it
+      unlicensed; it is MIT, verified by reading the file. The v5-to-v6 API break
+      was severe, so most tutorials and Stack Overflow answers online are for the
+      old `react-xr` package and will not compile. Testing requires real hardware
+      or the browser XR emulator extension, which makes CI coverage
+      effectively impossible — do not promise tested XR templates.
+
+  - name: threlte/threlte
+    url: https://github.com/threlte/threlte
+    stars: 3299
+    spdx: MIT
+    spdxSource: github-license-detection
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-06-11T11:36:51Z"
+    stack: typescript, svelte, three
+    complexity: standard
+    proposedLayerIds:
+      - render-threlte-svelte
+      - render-threejs
+      - physics-rapier
+      - build-vite-ts
+      - assets-gltf-loader
+    whatToBorrow: >-
+      The Svelte answer to R3F, and the better choice when per-frame overhead
+      matters — Svelte's compiled reactivity avoids the reconciliation cost that
+      forces R3F code into ref-mutation workarounds. Take the `<Canvas>` +
+      `<T.Mesh>` component model (the `T` namespace maps any Three.js class to a
+      component without a manual `extend()` registry, which is genuinely cleaner
+      than the R3F equivalent), the `useTask` render-loop hook with its explicit
+      task-ordering/stages system, and the monorepo split across
+      `packages/core`, `extras`, `rapier`, `theatre` and `xr` — that package
+      boundary is a good model for how Groundplan should slice 3D layers. The
+      `@threlte/gltf` CLI, which turns a .glb into a typed Svelte component, is
+      worth adapting for any asset-pipeline layer.
+    whatToAvoid: >-
+      Smaller ecosystem than R3F: fewer prebuilt helpers, so more will be written
+      by hand. It tracks Svelte's own major versions (runes/Svelte 5), meaning a
+      template pins both Svelte and Threlte majors together and inherits two
+      upgrade treadmills. Some sub-packages (theatre, xr) are markedly less
+      mature than core — verify before committing a layer to them.
+
+  - name: tresjs/tres
+    url: https://github.com/tresjs/tres
+    stars: 3628
+    spdx: MIT
+    spdxSource: github-license-detection
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-15T08:50:00Z"
+    stack: typescript, vue, three
+    complexity: standard
+    proposedLayerIds:
+      - render-tres-vue
+      - render-threejs
+      - build-vite-ts
+      - build-nuxt
+      - controls-orbit
+    whatToBorrow: >-
+      The Vue equivalent, and the most actively developed of the three framework
+      bindings listed here. Borrow the `<TresCanvas>` configuration and the
+      convention that any Three.js class is available as `<TresMesh>`,
+      `<TresPerspectiveCamera>` and so on via a compiler-level catalogue — no
+      import or registration step, which makes it the lowest-ceremony of the
+      framework wrappers. Take the `useLoop` composable for the render loop, the
+      `useTresContext` provide/inject pattern for reaching renderer internals,
+      and the `@tresjs/cientos` package as the drei-equivalent helper layer.
+      The official Nuxt module is worth adapting for the SSR story, since it
+      handles the client-only boundary that otherwise breaks 3D under SSR.
+    whatToAvoid: >-
+      The prop-passing convention (`:args`, kebab-vs-camel casing, `.prop`
+      modifiers) is unusual and a common source of silent no-ops where a
+      misspelled prop simply does nothing rather than erroring. Ecosystem depth
+      trails both R3F and Threlte, and helper coverage in cientos is uneven.
+      Vue 2 is entirely unsupported — do not offer this layer to a Vue 2 target.
+
+  - name: TheBevyFlock/bevy_new_2d
+    url: https://github.com/TheBevyFlock/bevy_new_2d
+    stars: 470
+    spdx: MIT OR Apache-2.0 OR CC0-1.0   # disjunctive: LICENSE-MIT.txt, LICENSE-Apache-2.0.txt, LICENSE-CC0-1.0.txt all present; GitHub's sidebar surfaces only "MIT"
+    spdxSource: LICENSE-file   # sidebar under-reports the tri-license; the three LICENSE-*.txt files were read directly
+    licenseClass: vendorable   # all three options are vendorable; take MIT and carry its notice
+    maintained: true
+    lastCommit: "2026-05-09T22:16:48Z"
+    stack: rust, bevy
+    complexity: standard
+    proposedLayerIds:
+      - engine-bevy
+      - ecs-bevy
+      - build-cargo
+      - ci-github-actions-release
+      - audio-bevy
+    whatToBorrow: >-
+      The community-standard Bevy game template and the best available model for
+      structuring a Rust ECS game, which is otherwise an unsolved question for
+      newcomers. Take the `src/screens/` module split (splash -> loading -> title
+      -> gameplay as distinct `Screen` states driven by Bevy's `States` +
+      `OnEnter`/`OnExit` system scheduling) — that state machine is the reusable
+      core. Also adapt `src/asset_tracking.rs`, which implements
+      load-before-you-enter resource tracking, and `src/audio.rs` (a single file,
+      not a directory) for the split between one-shot SFX and looping music with
+      independent volume controls. `src/menus/`, `src/theme/` and
+      `src/dev_tools.rs` are also worth lifting. The
+      `Cargo.toml` profile section is quietly the most valuable file:
+      `[profile.dev] opt-level = 1` with `[profile.dev.package."*"] opt-level = 3`
+      is what makes Bevy dev builds tolerable, and the release profile enables
+      LTO and strip. The GitHub Actions workflow builds and publishes web plus
+      desktop artifacts, including the wasm-bindgen and itch.io upload steps.
+    whatToAvoid: >-
+      Bevy's pre-1.0 releases still break APIs meaningfully at each minor
+      version, and the template tracks them — pin the Bevy version in any
+      generated project and expect migration work per upgrade. It is a 2D
+      template despite this category's 3D framing; the screens/assets/audio
+      scaffolding transfers to 3D unchanged, but the rendering and camera code
+      does not. Compile times are the standing complaint: without the dynamic
+      linking feature and a fast linker (both configured in the template, keep
+      them) iteration is slow. Small star count reflects both the template-repo
+      effect and Rust gamedev's overall size.
+
+  - name: godotengine/godot-demo-projects
+    url: https://github.com/godotengine/godot-demo-projects
+    stars: 9187
+    spdx: MIT
+    spdxSource: github-license-detection
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-15T18:11:33Z"
+    stack: gdscript, csharp, godot
+    complexity: standard
+    proposedLayerIds:
+      - engine-godot
+      - netcode-godot-multiplayer
+      - xr-openxr-godot
+      - physics-godot-3d
+      - ci-godot-export
+    whatToBorrow: >-
+      The official first-party demo collection and — importantly for this
+      category — a permissively licensed one, which is exactly what Unity's
+      equivalent is not. Each subdirectory is a self-contained project with its
+      own `project.godot`, making it unusually easy to lift a single pattern.
+      Highest value: `3d/platformer` and `3d/kinematic_character` for
+      `CharacterBody3D` movement and `move_and_slide` conventions,
+      `networking/multiplayer_bomber` for the high-level MultiplayerAPI with
+      `@rpc` annotations and `MultiplayerSpawner`/`MultiplayerSynchronizer`
+      nodes, `xr/openxr_*` for the OpenXR rig, and `loading/threaded_loading`
+      for `ResourceLoader.load_threaded_request`. The `project.godot` files
+      themselves are the template payload: rendering method, physics tick,
+      window stretch mode and input map defaults.
+    whatToAvoid: >-
+      Demos are teaching artifacts, not production scaffolds — no save systems,
+      no settings persistence, no localization, and error handling is usually
+      absent. Quality varies significantly between directories and some demos
+      lag the current Godot release; check each project's `config/features`
+      version before adapting. The repo is branched per Godot major version, so
+      vendoring from the wrong branch produces a project that will not open.
+      GDScript and C# coverage is uneven, with C# a distinct minority.
+
+  # ---------------------------------------------------------- professional ---
+
+  - name: phaserjs/phaser
+    url: https://github.com/phaserjs/phaser
+    stars: 39980
+    spdx: MIT
+    spdxSource: github-license-detection
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-09T14:28:26Z"
+    stack: javascript, typescript, webgl, canvas
+    complexity: professional
+    proposedLayerIds:
+      - engine-phaser
+      - physics-arcade
+      - physics-matter
+      - assets-spritesheet-atlas
+      - input-pointer-keyboard
+      - audio-webaudio
+    whatToBorrow: >-
+      The most battle-tested 2D web engine, with a decade of shipped commercial
+      games behind it. For Groundplan, borrow the architecture rather than the source:
+      the Scene lifecycle contract (`init` -> `preload` -> `create` -> `update`)
+      is the cleanest game-loop convention in web gamedev and transfers to
+      engines that lack one. Adapt the two-tier physics story — Arcade (AABB
+      only, extremely fast, the correct default) versus Matter.js (full rigid
+      body) selected per-scene rather than per-project — as a physics layer
+      decision point. The Loader's pack-file format and texture-atlas handling is
+      a ready-made asset pipeline, and the `scale` manager's `FIT`/`RESIZE`
+      modes with `autoCenter` solve responsive canvas sizing properly. Its
+      WebGL pipeline system is a good reference for custom shader integration.
+    whatToAvoid: >-
+      2D only — despite living in this category it will not serve any 3D layer,
+      and attempts to fake 3D in it are a trap. The full bundle is large; a real
+      template needs custom builds or tree-shaking config to avoid shipping
+      physics engines the game never uses. TypeScript types are generated from
+      JSDoc and are noticeably weaker than a native-TS engine's, with `any`
+      appearing in places that matter. Phaser 3 to 4 migration is ongoing in the
+      ecosystem, so pin the major and check which one any borrowed example
+      targets.
+
+  - name: colyseus/colyseus
+    url: https://github.com/colyseus/colyseus
+    stars: 7097
+    spdx: MIT
+    spdxSource: github-license-detection
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-06-23T15:31:37Z"
+    stack: typescript, node, websocket
+    complexity: professional
+    proposedLayerIds:
+      - netcode-colyseus
+      - state-sync-schema
+      - matchmaking-rooms
+      - scaling-redis-presence
+      - server-node-express
+      - auth-jwt
+    whatToBorrow: >-
+      The strongest permissive authoritative-multiplayer server in the JS
+      ecosystem and the natural backend layer for every client engine in this
+      file. Borrow the Schema system (`@colyseus/schema`) — decorated state
+      classes that produce binary deltas so only changed fields cross the wire —
+      which is the piece that is genuinely hard to build and easy to adapt. Take
+      the room lifecycle and `setSimulationInterval` for fixed-tick server logic,
+      `state.listen()`/`onChange` on the client for reactive binding, and the
+      `RedisPresence` + `RedisDriver` pairing that lets rooms be discovered
+      across a multi-process deployment — that is the whole horizontal-scaling
+      story and it is only a config swap from the single-process default.
+      `@colyseus/auth` and the `onAuth` hook give a clean pre-join
+      authentication seam. Client SDKs exist for Unity, Godot, Defold and
+      Haxe, so one server layer serves several engine templates.
+    whatToAvoid: >-
+      Rooms are stateful and in-memory, so a crashed process loses live game
+      state unless you add persistence yourself — the template must not imply
+      otherwise. It is TCP/WebSocket only; genuinely latency-critical action
+      games want UDP/WebRTC (geckos.io is the permissive alternative there).
+      The hosted Colyseus Cloud is the maintainers' commercial product, which is
+      a soft pull toward their infrastructure — self-hosting is fully supported
+      but less documented, so a template should include its own Dockerfile
+      rather than lean on the cloud path. Schema has a hard 64-field-per-class
+      limit that surprises people late.
+
+  - name: MirrorNetworking/Mirror
+    url: https://github.com/MirrorNetworking/Mirror
+    stars: 6249
+    spdx: MIT
+    spdxSource: github-license-detection
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-14T15:54:09Z"
+    stack: csharp, unity
+    complexity: professional
+    proposedLayerIds:
+      - netcode-mirror-unity
+      - engine-unity
+      - state-sync-syncvar
+      - transport-kcp-udp
+      - matchmaking-lobby
+    whatToBorrow: >-
+      The one genuinely vendorable Unity multiplayer stack — Unity's own
+      first-party Netcode for GameObjects is Unity Companion License and
+      therefore unusable as source material, which makes Mirror's MIT license
+      the deciding factor rather than a footnote. Borrow the `NetworkBehaviour`
+      model: `[SyncVar(hook = ...)]` fields for state replication,
+      `[Command]`/`[ClientRpc]`/`[TargetRpc]` for the authority-crossing call
+      convention, and `SyncList`/`SyncDictionary` for collections. Take the
+      `NetworkManager` + `NetworkRoomManager` lobby flow and the spawn/prefab
+      registration system, plus the pluggable Transport abstraction — KCP over
+      UDP as the reliable default with Telepathy (TCP) and WebSockets as
+      alternates is a good model for any transport layer. Interest management
+      (spatial hashing) is production-grade and worth studying for any
+      large-world template.
+    whatToAvoid: >-
+      Unity-only and Unity-version-coupled; it uses IL post-processing (weaving)
+      to generate serialization, which means obscure build-time errors when
+      Unity's compilation pipeline changes and poor interaction with some IL2CPP
+      and code-stripping settings. Its heritage is the deprecated UNet API, so
+      some naming and design decisions are inherited rather than chosen. The
+      project has a paid-support/commercial-services side and several forks
+      (Fish-Networking, Mirage) exist precisely because of past governance
+      disagreements — worth knowing before standardizing on it.
+
+  - name: playcanvas/engine
+    url: https://github.com/playcanvas/engine
+    stars: 16258
+    spdx: MIT
+    spdxSource: github-license-detection
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-18T13:17:38Z"
+    stack: javascript, typescript, webgl, webgpu
+    complexity: professional
+    proposedLayerIds:
+      - render-playcanvas
+      - webgpu-renderer
+      - ecs-playcanvas
+      - assets-gltf-loader
+      - perf-mobile
+      - render-gaussian-splatting
+    whatToBorrow: >-
+      A full engine rather than a rendering library — the entity-component
+      system, asset registry, input, audio and scene graph all ship together,
+      which makes it the closest thing here to "Unity for the web" under an MIT
+      license. Borrow the `pc.Entity` + `addComponent('render'|'rigidbody'|
+      'script')` ECS conventions and the ScriptType lifecycle
+      (`initialize`/`update`/`postUpdate`/`swap`) — the `swap` hot-reload hook is
+      a pattern worth stealing outright. Its WebGPU backend is among the most
+      complete in production JS engines and the graphics-device abstraction
+      cleanly hides the WebGL2/WebGPU split, which is the right shape for a
+      future-proof renderer layer. Mobile performance work is exceptionally
+      thorough and the Gaussian-splatting support is first-class, making it the
+      strongest pick for a splat/photogrammetry viewer template.
+    whatToAvoid: >-
+      The engine is MIT but the well-known PlayCanvas *Editor* is a proprietary
+      hosted product — do not let a template's docs blur the two, and build the
+      code-first path only. Smaller community than Three.js means fewer
+      third-party examples and more reading of source. The physics component
+      requires the external Ammo.js WASM build, which is a separate asset to load
+      and configure. Historically the engine assumed the editor's asset pipeline,
+      so some code-first workflows are less documented than they should be.
+
+  # ------------------------------------------------------------ enterprise ---
+
+  - name: mrdoob/three.js
+    url: https://github.com/mrdoob/three.js
+    stars: 113825
+    spdx: MIT
+    spdxSource: github-license-detection
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-18T09:09:00Z"
+    stack: javascript, typescript, webgl, webgpu, glsl
+    complexity: enterprise
+    proposedLayerIds:
+      - render-threejs
+      - webgpu-renderer
+      - shaders-glsl
+      - postfx-postprocessing
+      - assets-gltf-loader
+      - lighting-environment-hdri
+      - controls-orbit
+    whatToBorrow: >-
+      The substrate the majority of this category sits on, and the single richest
+      pool of adaptable 3D code that exists under MIT. The `examples/jsm/`
+      directory is the real asset: `controls/OrbitControls.js` and
+      `TransformControls.js`, `loaders/GLTFLoader.js` with its DRACO and KTX2
+      companions, the entire `postprocessing/` chain (`EffectComposer` +
+      `RenderPass` + `UnrealBloomPass` is the canonical bloom setup),
+      `utils/BufferGeometryUtils.js` for merging geometry into single draw calls,
+      and `libs/stats.module.js`. Also borrow the `RGBELoader` +
+      `PMREMGenerator` sequence for HDRI environment lighting and the color
+      management defaults (`outputColorSpace`, `toneMapping =
+      ACESFilmicToneMapping`) — those four lines account for most of the visual
+      gap between amateur and professional Three.js output. The `examples/`
+      HTML files are effectively 500+ single-file reference implementations.
+    whatToAvoid: >-
+      There is no stable API contract: three.js ships roughly monthly and
+      routinely makes breaking changes at minor versions, deleting deprecated
+      paths on a short clock — every template MUST pin an exact version, and
+      copied example code carries an expiry date. Nothing in `examples/jsm` is
+      covered by semver at all, so vendoring those files (which is the intended
+      use) means owning them thereafter. The library is unopinionated to a fault:
+      no ECS, no game loop beyond `requestAnimationFrame`, no asset manager, no
+      state — a template must supply all of it. The parallel WebGL and WebGPU
+      renderer tracks (including the TSL node-material system) are a genuine
+      fork in the road; choose one per template rather than straddling.
+
+  - name: BabylonJS/Babylon.js
+    url: https://github.com/BabylonJS/Babylon.js
+    stars: 25825
+    spdx: Apache-2.0
+    spdxSource: github-license-detection
+    licenseClass: vendorable   # NOTE: Apache-2.0 — the LICENSE.md and any NOTICE text must travel with copied files
+    maintained: true
+    lastCommit: "2026-07-16T22:59:26Z"
+    stack: typescript, webgl, webgpu, wasm
+    complexity: enterprise
+    proposedLayerIds:
+      - render-babylon
+      - webgpu-renderer
+      - physics-havok
+      - xr-webxr
+      - assets-gltf-loader
+      - editor-inspector-debug
+      - shaders-node-material
+    whatToBorrow: >-
+      The most batteries-included and most enterprise-appropriate 3D web engine —
+      Microsoft-backed, TypeScript-native, and the only one here whose stability
+      guarantees are strong enough for a long-lived internal product. Borrow the
+      `SceneLoader.ImportMeshAsync` / `AssetsManager` asset pipeline, the
+      `HavokPlugin` physics integration (Havok is the same physics used in
+      shipped AAA titles and is free for web use here), and the WebXR
+      `WebXRDefaultExperience` helper which is the fastest correct path to a VR
+      session. The Inspector (`scene.debugLayer.show()`) is a full in-browser
+      scene debugger that costs one line to enable and belongs in every template
+      behind a dev flag. Its Node Material Editor produces serialized JSON
+      materials that load at runtime — a genuinely differentiated pattern for
+      letting non-programmers author shaders. Backward compatibility is an
+      explicit project value, which is the opposite of three.js's posture and
+      the reason to choose it for regulated or long-support contexts.
+    whatToAvoid: >-
+      Apache-2.0, not MIT — this is the one license nuance in the file that
+      creates an obligation: copied files need the license and attribution
+      notice carried forward, so Groundplan's attribution step must handle it rather
+      than assuming MIT everywhere. The full bundle is heavy; use the
+      `@babylonjs/core` ES-module packages with side-effect imports rather than
+      the UMD build or templates will ship several megabytes. The API is verbose
+      and class-heavy compared to the R3F/Threlte declarative styles, and the
+      Havok plugin pulls a separate WASM binary needing its own bundler config.
+      Community examples overwhelmingly live in the Playground rather than in
+      the repo, which makes offline discovery harder than three.js's `examples/`.
+
+droppedCandidates:
+
+  - name: Unity-Technologies/com.unity.netcode.gameobjects
+    url: https://github.com/Unity-Technologies/com.unity.netcode.gameobjects
+    stars: 2316
+    spdx: NOASSERTION   # no SPDX id exists; LICENSE.md reads "Unity Companion License (UCL License)"
+    reason: >-
+      EXCLUDED ON LICENSE. GitHub detected no license; reading LICENSE.md on the
+      develop-2.0.0 branch shows the Unity Companion License, which permits use
+      only in Unity-dependent projects. That is a field-of-use restriction, not
+      an open-source grant, so it fails the vendorable gate and cannot even be
+      safely used as reference material for code we ship. Actively maintained
+      (last commit 2026-07-17) and technically the first-party choice — the
+      license is the only reason it is out. MirrorNetworking/Mirror (MIT) is
+      listed above as the permissive substitute.
+
+  - name: Unity-Technologies/com.unity.multiplayer.samples.coop
+    url: https://github.com/Unity-Technologies/com.unity.multiplayer.samples.coop
+    stars: 1950
+    spdx: NOASSERTION   # LICENSE.md reads "Licensed under the Unity Companion License"
+    reason: >-
+      EXCLUDED ON LICENSE. Unity's flagship "Boss Room" co-op sample and the best
+      teaching artifact for Unity multiplayer architecture, but same Unity
+      Companion License as above. Last commit 2025-10-23, so maintenance is not
+      the issue — the license is.
+
+  - name: pmndrs/react-three-next
+    url: https://github.com/pmndrs/react-three-next
+    stars: 2857
+    spdx: MIT
+    reason: >-
+      STALE. The most-recommended R3F + Next.js starter on the internet, and its
+      last commit is 2024-04-21 — 27 months before this research date, well past
+      the 18-month bar. It predates the Next.js App Router conventions it is
+      usually cited for. License is fine; it is simply dead. Its one durable idea
+      (a persistent shared canvas with DOM/3D view tunneling via tunnel-rat) is
+      worth reimplementing from scratch rather than vendoring.
+
+  - name: pmndrs/racing-game
+    url: https://github.com/pmndrs/racing-game
+    stars: 2206
+    spdx: MIT
+    reason: >-
+      STALE. Last commit 2023-02-23, over three years old. Frequently cited as
+      the reference R3F game project; its dependency tree (use-cannon rather than
+      rapier) is now the deprecated path.
+
+  - name: hyperfy-xyz/hyperfy
+    url: https://github.com/hyperfy-xyz/hyperfy
+    stars: 295
+    spdx: GPL-3.0
+    reason: >-
+      EXCLUDED ON LICENSE. GPL-3.0 would propagate copyleft terms to every repo
+      Groundplan generates from it. Interesting multiplayer-3D-worlds architecture,
+      but unusable as source material.
+
+  # Verified permissive, active, and viable — held back only to keep the list
+  # focused. Any of these can be promoted without re-verification effort:
+  #   o3de/o3de                        9519 stars, Apache-2.0, 2026-07-17
+  #     AAA-grade Linux Foundation engine; genuine enterprise tier, but far too
+  #     heavy to serve as scaffolding source material.
+  #   godotengine/godot              114286 stars, MIT,        2026-07-17
+  #     The engine itself; godot-demo-projects is the template-shaped surface.
+  #   geckosio/geckos.io               1489 stars, BSD-3-Clause, 2026-03-27
+  #     UDP/WebRTC netcode; the right answer where Colyseus's TCP is too slow.
+  #   excaliburjs/Excalibur            2316 stars, BSD-2-Clause, 2026-07-14
+  #   kaplayjs/kaplay                  1757 stars, MIT,         2026-07-17
+  #   galacean/engine                  5846 stars, MIT,         2026-03-20
+  #   NiklasEi/bevy_game_template      1130 stars, CC0-1.0,     2026-06-08
+  #   phaserjs/template-react-ts        197 stars, MIT,         2026-04-21
+  #   colyseus/colyseus-examples        194 stars, MIT,         2026-02-07
+  #   playcanvas/react                  514 stars, MIT,         2026-07-14
+  #   Sean-Bradley/Three.js-TypeScript-Boilerplate
+  #                                     589 stars, MIT,         2026-02-18