t1k:playablelabs:base:engine-free-package
| Field | Value |
|---|---|
| Module | base |
| Version | 2.29.2 |
| Effort | medium |
| Tools | — |
Keywords: container-free composition, engine-free package, library package, local api.ts, narrow local interface, no engine import, peerDependencies empty, ports and adapters, required constructor argument, rung model
How to invoke
Section titled “How to invoke”/t1k:playablelabs:base:engine-free-package[package to add or change]Engine-Free Package
Section titled “Engine-Free Package”Ported from theonekit-cocos t1k-cocos-base-engine-free-package v4.9.7 and made engine-neutral. A library
package in a game workspace runs inside a game (Cocos 3.8 or web/three.js) and knows nothing about the engine.
That keeps it testable without an engine, portable across games and enforceable by a gate rather than by review.
Scope split, so nothing is restated: the rule playablelabs-decouple-game-code.md says WHAT (public API only,
neutral core, automated gate). t1k-playablelabs-base-stdlib-contribute (references/decouple-from-three.md) says
how to strip three/cc types from a candidate being CONTRIBUTED to cocos-stdlib. This skill covers the other
half: how to SHAPE a package inside a workspace (rungs, sibling surfaces, composition, peers).
Rung model
Section titled “Rung model”Packages sit on rungs and imports only point downward. Prefixes differ per workspace; the workspace’s own
dependency gate (a script such as scripts/deps-check.*) is the authority, so read it before writing.
| Rung | Role | May import | May import the engine |
|---|---|---|---|
| 1 | core (data, host ports, utils) | nothing above rung 1 | no |
| 2 | feature | rung 1 | no |
| 3 | adapter | rungs 1-2 | no |
| top | ui / view | rungs 1-3 | yes (the only rung) |
An engine import (three, cc, type-only included) anywhere below the top rung is a gate failure, not style.
Composition: required arguments, not a container
Section titled “Composition: required arguments, not a container”No DI container. A package receives what it needs as constructor arguments; what matters is whether absence is legitimate.
- A data port or sibling feature it cannot work without is REQUIRED: absence is a compile error.
- A host capability that may legitimately be absent may no-op (analytics with no backend wired).
- Never silently no-op something whose absence changes behaviour: a bug with no error attached.
- A game-supplied registry (collectors, handlers, providers) is a constructor array argument, not a dependency; an empty array is usually ordinary configuration.
Sibling surfaces: declare, do not import
Section titled “Sibling surfaces: declare, do not import”A package that needs a sibling’s behaviour declares the narrow surface it actually calls in its own src/api.ts
and takes it as a constructor argument. It adds no peerDependency on the sibling.
// src/api.ts - narrowed from inventory. Only the credit is used: this feature never pays.export interface InventoryApi { addCurrency(currencyId: string, amount: number, source: string): void;}peerDependencies: {}with a README## RequiresreadingNone.is the intended shape when the only siblings are other features. Do not “fix” it into a dependency.- Spell each member exactly as the owning side declares it; a local shorthand grows a translation table.
{} is not universal. The rule is about what a package IMPORTS:
| The package imports | peerDependencies |
|---|---|
| only sibling feature surfaces, declared locally | {} |
| a lower-rung package | declare that peer |
A cross-package import needs a declared peer even when it is import type; a typical edge gate ignores type-only-ness.
Engine seams: ports and adapters
Section titled “Engine seams: ports and adapters”Same shapes as decouple-from-three.md (plain data types, dt/clock and RandomSource injected). The port is
either an object the package owns and exports, or a callback/interface the game implements. Never declare your own
copy of a class the game already has (buses match by constructor identity). The adapter that turns package output
into three meshes or cc nodes lives in the top rung or the game, never in the package.
Contracts and locks (when the workspace has them)
Section titled “Contracts and locks (when the workspace has them)”- Never hand-write a contract lock or edit the workspace lock; a generator produces them from a PUSHED contract. A hash of an uncommitted tree points at a revision that never existed.
- A dependency whose contract is not authored yet goes through the contract’s own escape hatch, not left dangling.
Verification loop
Section titled “Verification loop”Run the workspace dependency gate and the package unit suite, read the output, then claim a result. Then
mutation-test every load-bearing assertion: break the behaviour, confirm RED, restore. Report a surviving mutation as a
finding. bun test indents nested subtests, so read the # fail summary line; grepping ^not ok reports a false zero.
- A re-read getter is often load-bearing: capturing a live config value in the constructor passes most tests and freezes config at startup. Keep the getter; pin it with a test that changes the value between two calls.
- Local time is not UTC: mapping a local-time read onto a UTC surface is identical on a UTC CI machine and wrong for real players. Take a separate seam.
- A barrel re-export can drag in a dependency you do not use (one needing a credential to install). Import the specific module.
- Faithful beats tidy: where the source throws, throw (with a better message); do not change the outcome.
- A partial port is a success when it names what could not cross, with a
file:linecitation.
Related
Section titled “Related”playablelabs-decouple-game-code.md (rule) · t1k-playablelabs-base-stdlib-contribute · t1k-playablelabs-base-cpm-sweep · t1k-game-arch · t1k-library-decoupling