t1k:library-decoupling
| Field | Value |
|---|---|
| Module | t1k-library |
| Version | 2.7.50 |
| Effort | medium |
| Tools | — |
Keywords: asset-store decouple, cocos ts decoupling, creator meta uuid, decouple dependency, dynamic import, graceful degrade, interface provider, library decoupling, NoOp bridge, npm decouple, opt-in package, optional peer dependency, third-party, vendor seam, wasm base64, web bundler decoupling
How to invoke
Section titled “How to invoke”/t1k:library-decouplingLibrary Decoupling — Interface + Provider Seams (engine-agnostic)
Section titled “Library Decoupling — Interface + Provider Seams (engine-agnostic)”Enforces the mandate in references/third-party-decoupling.md: a library core never references a third-party dependency; vendor integrations live behind a library-owned interface in an opt-in bridge package, discovered at runtime/build-time, degrading gracefully (warn+skip or NoOp) when absent. Design the seam from the first line — never couple directly “for now.” This is the standard for ALL engines; per-stack mechanics live in references/.
When this fires
Section titled “When this fires”- About to write a third-party import/reference anywhere inside a shipped library package.
- A core package/target would need a hard reference to a vendor library.
- Decoupling an existing hard dependency.
- Managed-only effects (juice, tween, haptics, analytics, audio middleware) need to flow from core logic.
Decision tree
Section titled “Decision tree”Need a third-party API in the library?├─ Platform stdlib / engine-shipped / first-party? ──────── YES → hard ref is fine, done.├─ Caller is a test (test-only target)? ─────────────────── YES → vendor ref in test-only target OK; keep core clean.├─ Managed-only effect driven by core events/state? ─────── YES → library owns the event boundary + I*Bridge seam; vendor impl is consumer-side (Recipe B).└─ Otherwise (tooling or runtime vendor feature) ─────────→ Recipe A: interface + opt-in vendor package.Recipe A — interface + opt-in vendor package
Section titled “Recipe A — interface + opt-in vendor package”- Define the interface in core, generic types only — NO vendor types in any signature. Enumerate the FULL call surface first (incl. pre/post lifecycle hooks), not just the happy path — a bare
DoThing()that omits lifecycle calls won’t build once the vendor code moves out. - Orchestrator in core resolves the provider via the engine-idiomatic discovery mechanism (type/service registry, DI container, dynamic import, static self-registration) over the library’s OWN interface — never the vendor type. Make the resolver accept an injectable override for testability (default = the real discovery), so the “no provider” path is testable even when the host app ships a provider.
- Create the opt-in vendor package/module — the ONLY place the vendor import appears. It depends on core; core never depends on it.
- Consumer wiring: consumers who own the dependency add the opt-in package; others omit it → core builds clean, feature warns+skips / NoOps.
Recipe B — managed-effect seam (core events → vendor effect)
Section titled “Recipe B — managed-effect seam (core events → vendor effect)”- Library owns the event boundary + interface (e.g.
IScreenShakeBridge { Shake(pos, intensity); }) and the drain that converts core state/events into discrete effect calls. Put policy (thresholds, edge-detection, accessibility scaling) in the library drain so every consumer inherits it and impls stay dumb (“just play it”). - Vendor impl is consumer-side (not in the library). A single registered impl is the natural double-consumer guard.
Verification (run before claiming done)
Section titled “Verification (run before claiming done)”# core must be vendor-freegrep -rn "<VendorImport>" <core-package-path>/ # expect 0# vendor used in exactly one opt-in packagegrep -rln "<VendorImport>" <library-root>/ # expect only the opt-in vendor pkgThen: remove the vendor dependency + its opt-in package → project builds zero errors; trigger the feature → warn+skip / NoOp, surrounding tooling still works.
Engine mechanics
Section titled “Engine mechanics”- Unity (DOTS/C#): asmdef refs,
TypeCacheprovider discovery, Burst/lockfile gotchas, MonoBehaviour bridges → the engine mechanics ship withtheonekit-unity, not core. Core supplies the principle only; consult the Unity kit’s decoupling reference once that kit is installed. - Cocos / TS: interface + provider seams, DI, dynamic import of opt-in bridge packages, Creator
.metauuid stability →references/cocos-ts.md. - Web (vite/esbuild bundle): optional peer deps, dynamic
import()+ NoOp, tree-shaking, base64 wasm libs with an async init gate →references/web-bundler.md. - Other engines: add
references/<engine>.md(e.g. RN native-module optional deps) as they adopt the pattern.
Related
Section titled “Related”references/third-party-decoupling.md (the mandate this skill executes) ·
references/cocos-ts.md · references/web-bundler.md · t1k-game-arch (game-code side) ·
docs/library-quality-mandate.md · search-before-you-build.md (core) ·
rules/development-principles.md.