Skip to content

t1k:cocos:base:engine-free-package

FieldValue
Modulebase
Version4.51.9
Effortmedium
Tools—

Keywords: cocos engine-free package, container-free composition, contract lock, deps-check, library package, local api.ts, narrow local interface, no cc import, peerDependencies empty, pnpm workspace package, required constructor argument, rung model, tof-feature, vitest package tests

/t1k:cocos:base:engine-free-package
[package to add or change]

A package in this layer runs inside a Cocos game and knows nothing about Cocos. That is what makes it testable without an engine, portable across projects, and enforceable by a gate rather than by review. Every rule below exists to keep one of those three true.

Packages sit on rungs, and imports only ever point downward. A representative workspace (CocosTheOneFeature) uses four:

RungPrefixMay importMay import cc
1tof-core-*nothing above rung 1no
2tof-feature-*rung 1no
3tof-adapter-*rungs 1-2no
4tof-ui-*rungs 1-3yes

Only the top rung touches the engine. A cc import anywhere below it is a gate failure, not a style note — check the workspace’s scripts/deps-check.mjs for the exact rung names and checks before writing, because the prefixes differ per workspace and the gate is the authority.

Read the gate first. Knowing which of its checks apply to your rung before you write is the difference between one pass and a debugging loop.

Composition: required arguments, not a container

Section titled “Composition: required arguments, not a container”

There is no DI container. A package receives what it needs as constructor arguments, and the distinction that matters is whether absence is legitimate:

  • A data port or a sibling feature it cannot work without is REQUIRED. Absence is a compile error. A currency feature with no inventory is not a degraded currency feature, it is nothing.
  • A host capability that can legitimately be absent may no-op (analytics with no backend wired, for instance).

Never silently no-op something whose absence changes behaviour. That is a bug with no error attached to it, and nothing will report it.

A game-supplied registry is a constructor argument, not a dependency. A collection the consuming game implements and registers (collectors, handlers, providers) arrives as an array argument. It is not a contract dependency, and an empty array is usually an ordinary configuration rather than a degraded one — check the source before deciding it must be non-empty.

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 does not add a peerDependency and import 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;
}

Two consequences worth stating, because both look like mistakes and are not:

  • peerDependencies: {} with a README ## Requires reading None. is the intended shape for a package whose only siblings are other features. Do not “fix” it into a dependency.
  • Each member is spelled exactly as the owning side declares it. A local shorthand is how two engines end up with a translation table, which is the one artefact this layer exists to prevent.

But {} is NOT universal, and getting this backwards fails the gate. The rule is about what a package IMPORTS, not about how many constructor arguments it takes:

The package importspeerDependencies
only sibling FEATURE surfaces, declared locally{}
a lower-rung package (tof-core-data, tof-core-host, …)declare that peer

A cross-package import needs a declared peer even when it is import type. The gate’s cross-package edge pass does not consult type-only-ness — that is a separate check’s concern — so a type-only import of a rung-1 package with {} declared is a hard FAIL. In the representative workspace, piggy-bank, currency-progress, time and profile carry {} because they import no rung-1 package at all; inventory declares tof-core-data and two others declare tof-core-host, because they do.

Contracts and locks, when the workspace has them

Section titled “Contracts and locks, when the workspace has them”

Where a cross-engine contract governs the package, the contract is the vocabulary and the package implements it. Two rules:

  1. Never hand-write a contract.lock.json or edit the workspace lock. A generator produces them from a pushed contract. A sha computed from an uncommitted tree agrees with itself perfectly and points at a revision that never existed.
  2. A dependency whose contract is not authored yet is declared through the contract’s own escape hatch (a depCalls block, in the representative workspace) rather than left dangling.

Run all of it, read the output, then claim a result:

Terminal window
bun scripts/deps-check.mjs # architectural gate
bunx vitest@<pin> run --config vitest.config.mjs # unit suite

Then mutation-test every load-bearing assertion: break the behaviour, confirm the suite goes RED, restore it. A test you have not watched fail is unproven. Report a surviving mutation as a finding about the suite rather than quietly leaving it.

Counting note: bun test indents nested subtests, so read failures from the # fail summary line. Grepping ^not ok silently reports zero and has produced a false all-clear.

  • A re-read getter is often load-bearing. When the source reads a value through a service on every access, that value is live config with the local value as a fallback. Capturing it in the constructor passes nearly every test and silently freezes the config at startup. Keep the getter; pin it with a mutation test that changes the value between two calls.
  • Local time is not UTC. A source that exposes both a UTC clock and a local clock will have call sites using each. Mapping a local-time read onto a UTC surface produces values that are identical on a UTC machine and wrong by the offset everywhere else, so CI cannot see it and only real players hit it. Take a separate seam and say why.
  • A barrel re-export can drag in a dependency you do not use. Importing a package’s index for one symbol can pull a transitive dependency that needs a credential to install, making the suite unrunnable. Import the specific module instead.
  • Faithful beats tidy. Where the source throws, throw. Add a better message naming the offending value; do not change the outcome to summing, last-wins, or a swallowed error. That is a product decision, and nobody made it.
  • A partial port is a success when it names what could not cross. State the unportable piece with a file:line citation rather than approximating it.

t1k-cocos-base-clean-architecture (layering inside a package that needs it) · t1k-cocos-base-code-conventions · t1k-cocos-base-tsc-validate · agent t1k-cocos-base-package-developer (the implementer) · t1k-cocos-base-developer (the Creator layer this skill is explicitly not about)