t1k:unity:tof:registration
| Field | Value |
|---|---|
| Module | tof |
| Version | 3.46.8 |
| Effort | low |
| Tools | — |
Keywords: feature integration, Game.asmdef reference, gamelifetimescope, link.xml, opt-in provider, register, theonefeature, tof, tof di wiring, win flow, winflow
How to invoke
Section titled “How to invoke”/t1k:unity:tof:registrationTheOneFeature DI Registration
Section titled “TheOneFeature DI Registration”Scope — this is a candidate index, not an inventory. This skill indexes one source folder. A feature can span
Assets/TheOneFeature/,Packages/com.gdk.*, and siblingAssets/TheOne.*packages, and this skill will only show the folder it was built from. A capability missing here is not evidence that it is absent — verify against source (grep over a stated scope) before concluding anything does not exist. See The1Studio/theonekit-unity#350.
Integrating a TheOneFeature module into a Unity consumer project requires updating three files in lockstep. Missing any one produces a silent failure mode (compile OK + runtime null, or IL2CPP strip on device).
The Triplet
Section titled “The Triplet”| File | Purpose | Failure if skipped |
|---|---|---|
Assets/Scripts/GameLifetimeScope.cs | using + builder.Register<Feature>() call in Configure() | DI container has no binding → runtime VContainerException / null injection |
Assets/Scripts/Game.asmdef | Add the feature’s .DI assembly to references | Compile error: namespace not found |
Assets/Scripts/link.xml | <assembly fullname="..." preserve="all"/> | Works in Editor; IL2CPP strips on Android/iOS build → runtime crash on device only |
Canonical Pattern
Section titled “Canonical Pattern”// GameLifetimeScope.cs — top of fileusing TheOne.Features.RaceEvent.Core.DI;using TheOne.Features.PeriodRewardAds.DI;
// inside Configure(IContainerBuilder builder), in the feature-registration regionbuilder.RegisterRaceEvent();builder.RegisterPeriodRewardAds();Game.asmdef — append to the references array (asmdef is strict JSON, no comments allowed):
"TheOne.Features.RaceEvent.Core.DI","TheOne.Features.PeriodRewardAds.DI"<assembly fullname="TheOne.Features.RaceEvent" preserve="all"/><assembly fullname="TheOne.Features.PeriodRewardAds" preserve="all"/><assembly fullname="TheOne.Features.PeriodRewardAds.DI" preserve="all"/>Naming Conventions (Observed)
Section titled “Naming Conventions (Observed)”- DI namespace:
TheOne.Features.<FeatureName>[.Core].DI - Registration extension method:
builder.Register<FeatureName>()— match the method exported by the DI assembly (browse package source if unsure) link.xmlpreserves the runtime assembly (no.DIsuffix) AND the.DIassembly when a.DIexists separately. When in doubt, preserve both.
Sub-Feature Companions
Section titled “Sub-Feature Companions”Some features pull in UI/leaderboard companion assemblies that need their own preserves but no Register*() call. Examples:
PeriodRewardAds→ also preserveTheOne.Features.Puzzle.UI.Donate.Period,TheOne.Features.Puzzle.UI.IAA,TheOne.UI.Common.PeriodUI.Leaderboard.Core→ also requiresTheOne.Features.PlayFab.Coreas an asmdef reference even though there’s no directusing(transitive type leak via configs).
Opt-In Providers — the feature’s core DI call is still required
Section titled “Opt-In Providers — the feature’s core DI call is still required”A few features expose an opt-in provider seam: the feature ships a base capability, and a
provider is registered separately to make it active (the WinFlow family’s StreakLeaderboard and
MilestoneStreak are the known instances). Registering the provider alone is not enough — the
feature’s own core DI extension must be called too.
// inside Configure(IContainerBuilder builder), in the feature-registration regionbuilder.RegisterStreakLeaderboard(); // core DI — registers StreakLeaderboardDataController, the provider's depbuilder.RegisterMilestoneStreak();builder.RegisterStreakLeaderboardWinFlow(); // the opt-in provider itself (AsImplementedInterfaces)builder.RegisterMilestoneStreakWinFlow();The two calls live in different classes: the core extension is StreakLeaderboardVContainer in the
feature’s core .DI assembly; the provider extension is StreakLeaderboardWinFlowVContainer in the
opt-in .WinFlow.DI assembly. Confirmed dependency: StreakLeaderboardWinFlowProvider’s constructor
takes StreakLeaderboardDataController, which only RegisterStreakLeaderboard() registers.
Two distinct failure states — do NOT conflate them, because the obvious fix for A causes B:
| State | Shape | Symptom |
|---|---|---|
| A — config, no provider | the priority/config map names a provider that is never registered | Silent no-op. FeatureWinFlowService.ShowHighestPriorityAsync returns early on an empty provider collection with no log; the dead config is invisible at runtime. |
| B — provider without its feature’s core DI | the provider’s own Register*() call is present, the feature’s core extension is not | VContainerException at container build — the game does not boot. The provider is registered as a singleton implementing IFeatureWinFlowProvider, so it is constructed when the provider collection is resolved, and its constructor deps (e.g. StreakLeaderboardDataController) are unregistered. |
State B is what a naive fix for State A produces. Seeing A (dead config), the natural move is to
add the provider’s own Register*() call — which lands you in B, turning an invisible config bug
into a hard boot failure. Add the feature’s core DI extension in the same change as the
provider registration.
The Editor validator does not close this gap. StreakLeaderboardWinFlowValidator asks
RegistryResult(nameof(...RegisterStreakLeaderboardWinFlow)), which resolves to
RegistryUtils.HasRegistryMethod — that reads the root lifetime scope’s source file and evaluates
content.Contains($"builder.{methodName}()"). So it is a call-site check rather than a
type-existence one, but it is an exact-string check of one method name, and that is exactly what
State B slips through:
- It only ever looks for the provider’s own call. It never looks for the feature’s core
RegisterStreakLeaderboard(), so a project registering the provider alone — State B — validates green and then fails to boot. - The match is literal (
builder.<Name>()), sothis.builder.Register…(), a line-wrapped call, or any spacing variant reads as absent even when the call is there.
A green validator is not evidence the wiring is complete — assert both call sites directly:
grep -rn 'RegisterStreakLeaderboard\|RegisterMilestoneStreak' Assets/Scripts/GameLifetimeScope.csObserved in a consumer project. SgameArrow3D decommissioned the leaderboard cluster in
6dce1c79 (2026-07-28), removing RegisterStreakLeaderboard() and
RegisterStreakLeaderboardWinFlow() together — correctly, as a pair. But its
DefaultUserExperienceValue.asset still names streak_leaderboard and milestone_streak under
win_flow_popup_priority. That is State A: dead config, no log, nothing reports it. The realistic
route into State A is therefore not an omission — it is a partial decommission that removes the
registrations and leaves the priority config behind, so check both directions when a feature is
retired.
The map merely existing is not the signal — a second project (ArrowRomance) ships the same key as
an empty {}, which is harmless. The signal is an entry naming a feature whose Register*() is
absent.
Verification Steps
Section titled “Verification Steps”- Compile in Editor — confirms asmdef edits.
- Search for
[Inject]on the feature’s services to confirm theRegister*()extension actually binds them. - IL2CPP build on a device before declaring done — the only way to catch a missing
link.xmlentry. Editor and Mono builds will not surface the strip.
Order in Configure()
Section titled “Order in Configure()”Append new builder.Register*() calls inside the existing feature-registration region (after the last Register*() call, before #endregion). Do not reorder existing registrations — VContainer resolves lazily, but registration order matters when one feature’s Configure* lambda references another feature’s binding.
Hard rules
Section titled “Hard rules”asmdefis JSON, not JSON5 — no trailing commas, no comments. Many consumerGame.asmdeffiles have no trailing newline; preserve that to keep the diff minimal.link.xmlorder does not matter, but group related preserves together for diff readability.- No service-locator fallback. TheOneFeature modules are pure DI —
ProjectContext.Instance.Container.Resolve<T>()is forbidden by MainGame governance. All access must be via constructor[Inject]. - Avoid
RegisterX()outside the region. GameLifetimeScope has multiple#regionblocks; new TOF registrations belong in the same block as the existingRegisterLocalization()/RegisterDefaultClaimRewardHandler()calls. - An opt-in provider is two calls, not one — the provider’s
Register*WinFlow()AND the feature’s own coreRegister*(). Registering only the provider throwsVContainerExceptionat container build and the game will not boot. See “Opt-In Providers” above before wiring anyIFeatureWinFlowProvider.
New feature in a game: library first, contribute back
Section titled “New feature in a game: library first, contribute back”A game feature or meta-layer system comes from TOF when TOF has it: register it here, adapt through
its seams (IFeatureWinFlowProvider, config, blueprints), never copy or patch the submodule. When
TOF lacks a generic feature the game needs (verdict CONTRIBUTE, t1k:unity:base:knowledge-sweep),
write it as a TOF module via /t1k:lib-contribute (skill t1k-lib-contribute, lib via
t1k-lib-registry), then register it from the game like any other. Overlay the TOF PR on the game
and compile-gate it (Preserve, asmdef, UniTask double-await, unobserved faults) before merging.
Long form: docs/library-first-contribute-back.md.
Submodule Bump → Consumer Migration
Section titled “Submodule Bump → Consumer Migration”Bumping the shared submodules (GameFoundation, UITemplate, TheOneFeature, TheOne.FTUE,
ThirdPartyServices) can break the triplet above in ways beyond a single obvious compile error. See
references/submodule-update-migration.md for the post-bump discovery/sequencing checklist —
including the known-breaks table, a boot-time (not compile-time) blueprint failure trap, and an
.asmdef-audit gotcha that otherwise triples false-positive dangling references. It cross-links
t1k:unity:base:messagepipe (SignalBus → MessagePipe) and t1k:unity:base:blueprint-migrate
(BlueprintFlow → CsvData<,>), the two migrations a bump most commonly requires.