Skip to content

t1k:library-decoupling

FieldValue
Modulet1k-library
Version2.7.50
Effortmedium
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

/t1k:library-decoupling

Library 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/.

  • 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.
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”
  1. 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.
  2. 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.
  3. Create the opt-in vendor package/module — the ONLY place the vendor import appears. It depends on core; core never depends on it.
  4. 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)”
  1. 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”).
  2. Vendor impl is consumer-side (not in the library). A single registered impl is the natural double-consumer guard.
# core must be vendor-free
grep -rn "<VendorImport>" <core-package-path>/ # expect 0
# vendor used in exactly one opt-in package
grep -rln "<VendorImport>" <library-root>/ # expect only the opt-in vendor pkg

Then: remove the vendor dependency + its opt-in package → project builds zero errors; trigger the feature → warn+skip / NoOp, surrounding tooling still works.

  • Unity (DOTS/C#): asmdef refs, TypeCache provider discovery, Burst/lockfile gotchas, MonoBehaviour bridges → the engine mechanics ship with theonekit-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 .meta uuid 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.

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.