@aosengine/create-aosengine

Interfaces

ArgSpec

What a command accepts.

Properties

alias?

readonly optional alias?: Readonly<Record<string, string>>;

Single-character aliases, for example { t: 'template' }.

boolean?

readonly optional boolean?: readonly string[];

Option names that are true, false (via --no-x) or absent.

value?

readonly optional value?: readonly string[];

Option names that consume the following token, for example port.

---

ParsedArgs

The result of parseArgs.

Properties

flags

readonly flags: Readonly<Record<string, string | boolean>>;

Declared options that were present.

positionals

readonly positionals: readonly string[];

Everything that was not an option, in order.

unknown

readonly unknown: readonly string[];

Tokens that looked like options but were not declared.

---

ScaffoldOptions

Everything scaffold needs.

Properties

aam

readonly aam: boolean;

Wire up the AvatarOS Asset Manager in .env.example.

manifest

readonly manifest: TemplateManifest;

The template's declaration.

name

readonly name: string;

The new game's package name.

targetDir

readonly targetDir: string;

Absolute, forward-slashed directory to create.

templateDir

readonly templateDir: string;

Absolute, forward-slashed template directory.

title

readonly title: string;

The new game's human title.

versions

readonly versions: VersionContext;

How engine dependencies are pinned.

---

ScaffoldResult

What scaffold wrote.

Properties

files

readonly files: string[];

Every file written, relative to the target directory, sorted.

tokens

readonly tokens: TokenMap;

Tokens that were substituted.

---

Template

One template, located on disk.

Properties

dir

readonly dir: string;

Absolute, forward-slashed directory.

manifest

readonly manifest: TemplateManifest;

The template's own declaration, with defaults filled in.

name

readonly name: string;

Directory name, which is also what --template takes.

---

TemplateManifest

What a template declares about itself.

Properties

description

readonly description: string;

One line for the template chooser.

exclude

readonly exclude: readonly string[];

Paths, relative to the template root, that are never copied.

name

readonly name: string;

Directory name, for example fps.

rename

readonly rename: Readonly<Record<string, string>>;

Paths renamed on the way out, for example _gitignore to .gitignore.

title

readonly title: string;

Human title, used in the generated README and index.html.

tokens

readonly tokens: TokenMap;

Default token values, overridden by the command line.

---

VersionContext

Everything engineDependency needs to decide.

Properties

gameDir

readonly gameDir: string;

Absolute path to the game being created, for relative file: links.

mode

readonly mode: LinkMode;

Published range, or file: links back into a checkout.

packagesDir?

readonly optional packagesDir?: string;

Directory containing npm-pack tarballs, required in packed mode.

repoRoot?

readonly optional repoRoot?: string;

The engine repository root, required in file mode.

version

readonly version: string;

The version to publish against, in semver mode.

Type Aliases

LinkMode

type LinkMode = "file" | "semver" | "packed";

How engine dependencies are pointed at the engine.

---

TokenMap

type TokenMap = Readonly<Record<string, string>>;

Values substituted into a template.

Variables

CREATE_HELP

const CREATE_HELP: string;

One screen of help.

---

CREATE_SPEC

const CREATE_SPEC: object;

Options create-aosengine accepts.

Type Declaration

alias

readonly alias: object;

alias.f

readonly f: "force" = 'force';

alias.h

readonly h: "help" = 'help';

alias.t

readonly t: "template" = 'template';

alias.v

readonly v: "version" = 'version';

boolean

readonly boolean: readonly ["install", "git", "aam", "third-person", "force", "help", "version"];

value

readonly value: readonly ["template", "title", "packages-dir"];

---

DEFAULT_MANIFEST

const DEFAULT_MANIFEST: Omit<TemplateManifest, "name" | "title">;

What a template gets when it ships no template.json.

---

GITIGNORE

const GITIGNORE: "node_modules/\ndist/\nbuild/\n.aosengine/\n.vite/\ncoverage/\ntest-results/\nplaywright-report/\n*.tsbuildinfo\n\n# Local environment. .env.example is committed; .env is not.\n.env\n.env.*.local\n.env.local\n\n.DS_Store\nThumbs.db\n";

The .gitignore every generated game gets, when the template has none.

---

PACKAGE

const PACKAGE: "@aosengine/create-aosengine";

Package identity marker.

Example

import { PACKAGE } from '@aosengine/create-aosengine';

console.log(PACKAGE); // '@aosengine/create-aosengine'

---

SHIPPED_AS

const SHIPPED_AS: Readonly<Record<string, string>>;

Files npm refuses to ship verbatim, and the names they travel under.

---

SKIP_DIRS

const SKIP_DIRS: Set<string>;

Directory names never copied out of a template.

---

SKIP_FILES

const SKIP_FILES: Set<string>;

File names never copied out of a template.

---

TEXT_EXTENSIONS

const TEXT_EXTENSIONS: Set<string>;

Extensions treated as text, and therefore token-substituted.

---

TEXT_NAMES

const TEXT_NAMES: Set<string>;

Files with no extension that are still text.

Functions

absPosix()

function absPosix(...parts): string;

Resolve to an absolute, forward-slashed path.

Parameters

Parameter	Type	Description
...parts	string[]	Path segments, resolved left to right against process.cwd().

Returns

string

An absolute path with / separators.

---

agentsMd()

function agentsMd(title, name): string;

The game-scoped AGENTS.md, written when the template does not ship one.

Parameters

Parameter	Type	Description
title	string	The game's title.
name	string	The game's package name.

Returns

string

The file contents.

---

applyTokens()

function applyTokens(text, tokens): string;

Replace every in a string.

Unknown tokens are left alone rather than blanked, so a mistake is visible in the generated file instead of silently producing an empty string.

Parameters

Parameter	Type	Description
text	string	The template text.
tokens	TokenMap	Values to substitute.

Returns

string

The substituted text.

---

engineDependency()

function engineDependency(
   name, 
   spec, 
   ctx
): string;

The version specifier a generated game should use for one dependency.

Anything that is not an engine package, and any engine package pinned to a real version, is left exactly as the template wrote it. Pinning is a hard rule here, not a preference.

Parameters

Parameter	Type	Description
name	string	The dependency name.
spec	string	What the template declared.
ctx	VersionContext	Publishing mode, version and paths.

Returns

string

The specifier to write into the game's package.json.

---

envExample()

function envExample(aam): string;

The .env.example a generated game gets.

Parameters

Parameter	Type	Description
aam	boolean	Whether the AvatarOS Asset Manager keys are included.

Returns

string

The file contents.

---

findRepoRoot()

function findRepoRoot(startDir): string | undefined;

Find the aosengine monorepo root above startDir, if there is one.

When the scaffolder is run from inside a checkout of the engine, generated games get file: links back at packages/ instead of published versions.

Parameters

Parameter	Type	Description
startDir	string	Absolute directory to start from.

Returns

string | undefined

The absolute, forward-slashed repository root, or undefined.

---

findTemplate()

function findTemplate(cwd, name): Template | undefined;

Find one template by name.

Parameters

Parameter	Type	Description
cwd	string	Where the command was run.
name	string	The --template value.

Returns

Template | undefined

The template, or undefined when it is not installed.

---

flagBool()

function flagBool(
   flags, 
   name, 
   fallback
): boolean;

Read a boolean flag.

Parameters

Parameter	Type	Description
flags	Readonly<Record<string, string | boolean | undefined>>	Parsed flags.
name	string	Option name.
fallback	boolean	Value to use when the option is absent.

Returns

boolean

The flag value.

---

flagNumber()

function flagNumber(
   flags, 
   name, 
   fallback
): number;

Read a numeric flag.

Parameters

Parameter	Type	Description
flags	Readonly<Record<string, string | boolean | undefined>>	Parsed flags.
name	string	Option name.
fallback	number	Value to use when the option is absent or unparseable.

Returns

number

The flag value.

---

flagString()

function flagString(
   flags, 
   name, 
   fallback
): string;

Read a string flag.

Parameters

Parameter	Type	Description
flags	Readonly<Record<string, string | boolean | undefined>>	Parsed flags.
name	string	Option name.
fallback	string	Value to use when the option is absent.

Returns

string

The flag value.

---

gamePackageJson()

function gamePackageJson(
   template, 
   name, 
   ctx
): Record<string, unknown>;

Build the game's own package.json from the template's.

Everything that only makes sense inside the monorepo is dropped: the workspace private flag, the files allow-list, and any workspaces key a template might have inherited.

Parameters

Parameter	Type	Description
template	Readonly<Record<string, unknown>>	The template's parsed manifest.
name	string	The new game's package name.
ctx	VersionContext	Publishing mode, version and paths.

Returns

Record<string, unknown>

The manifest to write, pretty-printed by the caller.

---

hoistExtendedTsconfig()

function hoistExtendedTsconfig(
   targetDir, 
   templateDir, 
   written
): void;

Make a copied tsconfig.json stand on its own.

Templates are workspace members, so their tsconfig.json usually extends the repository's tsconfig.base.json by a relative path that means nothing once the game is somewhere else. The base is copied in next to it and the extends string is rewritten — textually, so the comments survive.

One level only: a base that itself extends something outside the repository is not a shape this repository has.

Parameters

Parameter	Type	Description
targetDir	string	Absolute game directory.
templateDir	string	Absolute template directory the extends resolves against.
written	string[]	Accumulator of written paths.

Returns

void

---

isEnginePackage()

function isEnginePackage(name): boolean;

Is this an engine package?

Parameters

Parameter	Type	Description
name	string	A dependency name.

Returns

boolean

True for @aosengine/*.

---

isTextFile()

function isTextFile(fileName): boolean;

Is this file text, and therefore token-substituted?

Parameters

Parameter	Type	Description
fileName	string	A base name.

Returns

boolean

True when the file should be read as UTF-8 and substituted.

---

leftoverTokens()

function leftoverTokens(text): string[];

Every still present in a string.

Parameters

Parameter	Type	Description
text	string	Substituted text.

Returns

string[]

Distinct token names, sorted; empty when substitution was complete.

---

listTemplates()

function listTemplates(cwd): Template[];

List every template that is actually installed.

Parameters

Parameter	Type	Description
cwd	string	Where the command was run.

Returns

Template[]

Templates, sorted by name, first root wins on a duplicate.

---

main()

function main(argv, cwd): Promise<number>;

Run the scaffolder.

Parameters

Parameter	Type	Description
argv	readonly string[]	Arguments after the executable and script.
cwd	string	Directory the target path is resolved against.

Returns

Promise<number>

The process exit code.

---

normaliseManifest()

function normaliseManifest(name, raw): TemplateManifest;

Read a template.json, filling in everything it left out.

Parameters

Parameter	Type	Description
name	string	The template directory name.
raw	unknown	The parsed template.json, or undefined when there is none.

Returns

TemplateManifest

A complete manifest.

---

outputName()

function outputName(fileName, rename): string;

The name a file takes in the generated game.

npm strips .gitignore out of a published tarball, so templates ship theirs as _gitignore; this puts the dot back. A template's own rename map wins.

Parameters

Parameter	Type	Description
fileName	string	The name inside the template.
rename	Readonly<Record<string, string | undefined>>	The template's explicit renames.

Returns

string

The name to write.

---

ownVersion()

function ownVersion(): string;

This package's version, read from its own manifest.

Returns

string

The version string, or 0.0.0 when the manifest is unreadable.

---

packageDirOf()

function packageDirOf(moduleUrl): string;

The directory of the npm package a module belongs to.

Parameters

Parameter	Type	Description
moduleUrl	string	A module's import.meta.url.

Returns

string

The absolute, forward-slashed package directory.

---

parseArgs()

function parseArgs(argv, spec?): ParsedArgs;

Parse an argv slice.

Parameters

Parameter	Type	Description
argv	readonly string[]	Arguments after the command name.
spec	ArgSpec	What this command accepts.

Returns

ParsedArgs

Positionals, flags and anything undeclared.

---

readManifest()

function readManifest(dir, name): TemplateManifest;

Read a template's template.json, tolerating its absence.

Parameters

Parameter	Type	Description
dir	string	Absolute template directory.
name	string	Directory name, used as the fallback identity.

Returns

TemplateManifest

A complete manifest.

---

relativeSpecifier()

function relativeSpecifier(fromDir, toPath): string;

A relative path from one directory to another, for file: dependencies.

Falls back to the absolute path when the two are on different Windows drives, where no relative path exists.

Parameters

Parameter	Type	Description
fromDir	string	Absolute directory the path is written in.
toPath	string	Absolute target.

Returns

string

A relative path starting with ./ or ../, or an absolute one.

---

rewriteDependencies()

function rewriteDependencies(pkg, ctx): Record<string, unknown>;

Rewrite every dependency block of a template's package.json.

Parameters

Parameter	Type	Description
pkg	Readonly<Record<string, unknown>>	The parsed manifest. Not mutated.
ctx	VersionContext	Publishing mode, version and paths.

Returns

Record<string, unknown>

A new manifest with engine dependencies rewritten.

---

scaffold()

function scaffold(options): ScaffoldResult;

Copy a template into a new directory, substituting as it goes.

Parameters

Parameter	Type	Description
options	ScaffoldOptions	Where from, where to, and what to substitute.

Returns

ScaffoldResult

Which files were written.

Throws

When the template is missing a package.json.

---

stripDanglingSchema()

function stripDanglingSchema(
   targetDir, 
   templateDir, 
   relativePath
): void;

Remove a $schema key whose relative path does not survive the copy.

A template's src/assets.json points $schema at the repository's docs/schemas/assets.schema.json so editors complete it. That path dangles the moment the file is somewhere else, and parseManifest rejects unknown top-level keys, so the generated game would not boot. Absolute URLs are left alone: those keep working.

The edit is textual, so key order and formatting survive.

Parameters

Parameter	Type	Description
targetDir	string	Absolute game directory.
templateDir	string	Absolute template directory.
relativePath	string	The JSON file, relative to both roots.

Returns

void

---

templateRoots()

function templateRoots(cwd): string[];

Every directory that might hold templates, best first.

Parameters

Parameter	Type	Description
cwd	string	Where the command was run.

Returns

string[]

Absolute, forward-slashed candidate directories.

---

toPackageName()

function toPackageName(raw): string;

Turn a directory name into a package name npm will accept.

Parameters

Parameter	Type	Description
raw	string	What the user typed, for example My FPS!.

Returns

string

A lowercase, dash-separated name, for example my-fps.

---

toPosix()

function toPosix(path): string;

Forward-slash a path and drop any trailing separator.

Parameters

Parameter	Type	Description
path	string	Any path, in any separator style.

Returns

string

The same path with / separators and no trailing slash.

---

toTitle()

function toTitle(name): string;

Turn a package name into a human title.

Parameters

Parameter	Type	Description
name	string	A package name, for example my-fps.

Returns

string

A title, for example My Fps.