Skip to content

t1k:unity:base:gameplay-integration

FieldValue
Modulebase
Version5.116.6
Effortmedium
Tools—

Keywords: add a mechanic to template, add gameplay feature, first gameplay feature, gameplay integration, gameplay into template, integrate gameplay, tap to shrink, template extension points, TemplateLogGuard, touch-point ledger

/t1k:unity:base:gameplay-integration

Integrating Gameplay Into a Studio Template

Section titled “Integrating Gameplay Into a Studio Template”

Adding gameplay to a repo created from a The1Studio Unity template, by hanging new code off the template’s existing seams instead of beside them. Scope: AFTER the project boots (t1k:unity:base:template-bootstrap owns template to green build). This skill owns the first gameplay feature and every one after it.

Why it is its own skill: both templates already own a boot chain, DI scopes, a screen flow, blueprint loading, audio and input. A feature that ignores them compiles and then fails at boot, or fights the template for the same job. Every fact here was verified against a real working integration (tap-to-shrink cube on BaseUnityTemplate) and a read-only map of PuzzleTemplate.

QuestionAnswerRead
Which template is this repo?SetupProject.sh/.bat at root, or 3 submodules in .gitmodules: BaseUnityTemplate. setup-project.sh, or 7 submodules: PuzzleTemplatestep 0 below
BaseUnityTemplate: no gameplay layer exists yetYou build the run controller and win/lose wiringreferences/baseunitytemplate.md
PuzzleTemplate: has levels, win/lose, popupsEXTEND its seams, never build a run controllerreferences/puzzletemplate.md
Steps shared by both templatesdomain, signals, config, DI, input, testsreferences/core-procedure.md
Player-facing action (tap, hit, win)feedback is part of the same PRreferences/feedback.md
Writing or reviewing testsEditMode model tests, PlayMode smokereferences/testing.md
Something threw at boot or renders wrongsymptom to cause to fixreferences/incident-history.md
Want a concrete end-to-end example on BaseUnityTemplatetap-to-shrink cube, end to endreferences/example-tap-shrink.md
Want a concrete end-to-end example on PuzzleTemplatetap-to-win a Level entity, end to endreferences/example-tap-level-entity.md

Same detection as t1k:unity:base:template-bootstrap (cite it, do not restate). Then read the matching template reference BEFORE writing code. Never mix facts across templates: a registration site, end-game screen, audio group or asmdef name that is right for one is wrong for the other.

Each step names its proof. Do not start the next step on a failed proof. Detail and the per-template delta for every step are in references/core-procedure.md.

  1. Preflight. Read references/<template>.md; run git status; confirm the project compiles (t1k unity recompile 0 errors) BEFORE you change anything, so later errors are yours. Proof: clean baseline compile; template identified.
  2. Design contract first. Write the shared shape (domain API, signal fields, config columns, asset keys, feedback cells) in one file before coding any layer (skills/t1k-team/references/contract-first-integration.md (theonekit-core)). Proof: every later file names the contract.
  3. Domain layer, engine-free. Pure C# model + outcome enum + signal structs. BaseUnityTemplate: own asmdef with noEngineReferences: true, autoReferenced: false, referenced by name. PuzzleTemplate: no precedent for that asmdef, place game code per its own layout. Proof: grep -rn "UnityEngine" on the domain folder is empty.
  4. Signals (MessagePipe). public readonly struct signals, no per-signal registration; see t1k:unity:base:messagepipe. PT: PuzzleTemplate’s Level→popup path already runs on its own handlers — add a signal only for a genuinely new cross-layer event, never to replace one. Proof: publisher and subscriber resolve with no container error.
  5. Data-driven config. CSV blueprint: CSV, Addressables entry, THEN RegisterBlueprint<T>() (order matters). Template specifics differ (central vs per-feature registration, levels are not CSV in PuzzleTemplate). See t1k:unity:base:blueprint-csv and references/incident-history.md (#887, #888 corrections). Proof: boot reaches Home; changing a CSV value changes behaviour with no code edit.
  6. DI seams. Root scope for data and shared services, scene scope for scene objects and per-scene controllers. PT: the type from TheOne.DI (resolution) is not the one from TheOne.DI.VContainer (.GetCurrentContainer()); pick by which assembly already references which. Proof: the app boots with no VContainerException.
  7. Presentation. Thin presenter, view, prefab/scene wiring; the template’s own screen/popup system opens the end state. See t1k:unity:ui:create-prefab. PT: the host component goes on the level prefab’s Systems child, and the view target on that prefab’s own Canvas — resolve the two by fileID in the variant YAML. Proof: the flow is playable Home to end state and back (retry/next).
  8. Input. Both templates use legacy input and uGUI pointer events on the existing EventSystem. Put the target under the screen’s ViewRoot so closing the screen cuts raycasts. Proof: a real ExecuteEvents pointer-down reaches the handler.
  9. Feedback in the same change. Classify each action, fill its cells, ship placeholder slots, measure loudness. references/feedback.md. Proof: console closed, you can tell what happens.
  10. Verify once, at the end. Batch-implement, then one compile plus both test suites (rules/ai-velocity-batch-compile-unity.md, t1k:unity:testing:workflow). references/testing.md. Proof: 0 compile errors, all suites green, TemplateLogGuard reports nothing unexpected.
  11. Record the touch points. Keep a ledger row per extension point (file, add or edit, registration, why, verified-by). It is the acceptance test for the next integration.
  • Never register a blueprint before its Addressables entry exists (boot throws).
  • Never put a RegisterComponentInHierarchy object anywhere but a ROOT object of that scope’s scene.
  • Never add a Light to fix a black cube; use an Unlit material (neither template’s 1.MainScene has a Light).
  • Never edit submodule files in the game repo; extend from project-local code.
  • Never build a meta-layer feature (hub, shop/IAP, ads, wallet, claims, quests, event pass, talents, FTUE, settings, save, time) in the game when a studio lib ships it: take it from TOF / GameFoundation / UITemplate (t1k-unity-tof-registration), and send generic code you had to write back to the lib (/t1k:lib-contribute, skill t1k-lib-contribute, lib via t1k-lib-registry). The game keeps data, content and adapters. See docs/library-first-contribute-back.md.
  • Never LogAssert.ignoreFailingMessages = true for a whole run; use the allow-list guard.
  • Never claim done from compile + green EditMode alone: run the PlayMode path through real input.

t1k:unity:base:blueprint-csv (CSV authoring) / t1k:unity:base:messagepipe (signals) / t1k:unity:ui:create-prefab (screen prefabs) / addressables (groups, keys) / t1k:unity:testing:workflow (running suites) / template-bootstrap (boot to green) / t1k:game-arch (layer rules) / rules/game-feedback-mandate-unity.md and rules/game-asset-slot-handoff-unity.md (feedback contract; each extends a designer-kit parent — rules/game-feedback-mandate.md and rules/placeholder-first-handoff.md, which are not installed here) / rules/observable-gameplay.md (theonekit-designer, not installed in a Unity-only repo).

Runs inline in the main session or under t1k-unity-base-developer, which implements; t1k-unity-base-mono-tester runs the suites in step 10. Judgment stays with the implementer.

Full symptom/cause/fix list: references/incident-history.md. The three that cost the most time: blueprint entry-before-register ordering, a scene-scope object not being a root of its scene, and a blanket log ignore hiding a real exception.