Skip to content

t1k:unity:tof:registration

FieldValue
Moduletof
Version3.46.8
Effortlow
Tools—

Keywords: feature integration, Game.asmdef reference, gamelifetimescope, link.xml, opt-in provider, register, theonefeature, tof, tof di wiring, win flow, winflow

/t1k:unity:tof: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 sibling Assets/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).

FilePurposeFailure if skipped
Assets/Scripts/GameLifetimeScope.csusing + builder.Register<Feature>() call in Configure()DI container has no binding → runtime VContainerException / null injection
Assets/Scripts/Game.asmdefAdd the feature’s .DI assembly to referencesCompile 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
// GameLifetimeScope.cs — top of file
using TheOne.Features.RaceEvent.Core.DI;
using TheOne.Features.PeriodRewardAds.DI;
// inside Configure(IContainerBuilder builder), in the feature-registration region
builder.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"
link.xml
<assembly fullname="TheOne.Features.RaceEvent" preserve="all"/>
<assembly fullname="TheOne.Features.PeriodRewardAds" preserve="all"/>
<assembly fullname="TheOne.Features.PeriodRewardAds.DI" preserve="all"/>
  • 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.xml preserves the runtime assembly (no .DI suffix) AND the .DI assembly when a .DI exists separately. When in doubt, preserve both.

Some features pull in UI/leaderboard companion assemblies that need their own preserves but no Register*() call. Examples:

  • PeriodRewardAds → also preserve TheOne.Features.Puzzle.UI.Donate.Period, TheOne.Features.Puzzle.UI.IAA, TheOne.UI.Common.PeriodUI.
  • Leaderboard.Core → also requires TheOne.Features.PlayFab.Core as an asmdef reference even though there’s no direct using (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 region
builder.RegisterStreakLeaderboard(); // core DI — registers StreakLeaderboardDataController, the provider's dep
builder.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:

StateShapeSymptom
A — config, no providerthe priority/config map names a provider that is never registeredSilent 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 DIthe provider’s own Register*() call is present, the feature’s core extension is notVContainerException 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>()), so this.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:

Terminal window
grep -rn 'RegisterStreakLeaderboard\|RegisterMilestoneStreak' Assets/Scripts/GameLifetimeScope.cs

Observed 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.

  1. Compile in Editor — confirms asmdef edits.
  2. Search for [Inject] on the feature’s services to confirm the Register*() extension actually binds them.
  3. IL2CPP build on a device before declaring done — the only way to catch a missing link.xml entry. Editor and Mono builds will not surface the strip.

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.

  • asmdef is JSON, not JSON5 — no trailing commas, no comments. Many consumer Game.asmdef files have no trailing newline; preserve that to keep the diff minimal.
  • link.xml order 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 #region blocks; new TOF registrations belong in the same block as the existing RegisterLocalization() / RegisterDefaultClaimRewardHandler() calls.
  • An opt-in provider is two calls, not one — the provider’s Register*WinFlow() AND the feature’s own core Register*(). Registering only the provider throws VContainerException at container build and the game will not boot. See “Opt-In Providers” above before wiring any IFeatureWinFlowProvider.

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.

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.