t1k:unity:base:gameplay-integration
| Field | Value |
|---|---|
| Module | base |
| Version | 5.116.6 |
| Effort | medium |
| 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
How to invoke
Section titled “How to invoke”/t1k:unity:base:gameplay-integrationIntegrating 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.
Decision Tree
Section titled “Decision Tree”| Question | Answer | Read |
|---|---|---|
| Which template is this repo? | SetupProject.sh/.bat at root, or 3 submodules in .gitmodules: BaseUnityTemplate. setup-project.sh, or 7 submodules: PuzzleTemplate | step 0 below |
| BaseUnityTemplate: no gameplay layer exists yet | You build the run controller and win/lose wiring | references/baseunitytemplate.md |
| PuzzleTemplate: has levels, win/lose, popups | EXTEND its seams, never build a run controller | references/puzzletemplate.md |
| Steps shared by both templates | domain, signals, config, DI, input, tests | references/core-procedure.md |
| Player-facing action (tap, hit, win) | feedback is part of the same PR | references/feedback.md |
| Writing or reviewing tests | EditMode model tests, PlayMode smoke | references/testing.md |
| Something threw at boot or renders wrong | symptom to cause to fix | references/incident-history.md |
| Want a concrete end-to-end example on BaseUnityTemplate | tap-to-shrink cube, end to end | references/example-tap-shrink.md |
| Want a concrete end-to-end example on PuzzleTemplate | tap-to-win a Level entity, end to end | references/example-tap-level-entity.md |
Step 0 - Detect the template
Section titled “Step 0 - Detect the template”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.
Core steps
Section titled “Core steps”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.
- Preflight. Read
references/<template>.md; rungit status; confirm the project compiles (t1k unity recompile0 errors) BEFORE you change anything, so later errors are yours. Proof: clean baseline compile; template identified. - 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. - 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. - Signals (MessagePipe).
public readonly structsignals, no per-signal registration; seet1k: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. - 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). Seet1k:unity:base:blueprint-csvandreferences/incident-history.md(#887, #888 corrections). Proof: boot reaches Home; changing a CSV value changes behaviour with no code edit. - 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 fromTheOne.DI.VContainer(.GetCurrentContainer()); pick by which assembly already references which. Proof: the app boots with noVContainerException. - 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’sSystemschild, 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). - 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
ExecuteEventspointer-down reaches the handler. - 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. - 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,TemplateLogGuardreports nothing unexpected. - 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
RegisterComponentInHierarchyobject 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.MainScenehas 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, skillt1k-lib-contribute, lib viat1k-lib-registry). The game keeps data, content and adapters. Seedocs/library-first-contribute-back.md. - Never
LogAssert.ignoreFailingMessages = truefor a whole run; use the allow-list guard. - Never claim done from compile + green EditMode alone: run the PlayMode path through real input.
Cross-links (do not duplicate)
Section titled “Cross-links (do not duplicate)”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).
Executed by
Section titled “Executed by”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.
Hard rules
Section titled “Hard rules”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.