@v12-engine/engine 0.0.0-stage → 0.1.0

package/dist/profiles-B3NS9jwk.js

@@ -0,0 +1,335 @@
+//#region src/ai/settings.ts
+/**
+* Where each flag that an area has a name for goes in it, and whether it is a share (`true`: the share a lower layer or
+* the area gives; a number: that share; `false`: never)
+*/
+var FLAGGED = {
+	defendUsers: [["team", "defendUsers"], "switch"],
+	say: [["team", "say"], "switch"],
+	targetHeroes: [["micro", "targetHeroes"], "switch"],
+	ignoreInjured: [["micro", "ignoreInjured"], "switch"],
+	removeInjuries: [["micro", "removeInjuries"], "switch"],
+	takeItems: [["micro", "takeItems"], "switch"],
+	buyItems: [["micro", "buyItems"], "switch"],
+	smartArtillery: [["micro", "smartArtillery"], "switch"],
+	kite: [["micro", "kite"], "switch"],
+	unitsFlee: [["micro", "unitsFlee"], "share"],
+	heroesFlee: [["micro", "heroesFlee"], "share"],
+	groupsFlee: [["squads", "retreatAt"], "share"],
+	workersFlee: [["economy", "workersFlee"], "switch"],
+	repairStructures: [[
+		"plans",
+		"build",
+		"repair"
+	], "switch"],
+	rebuild: [[
+		"plans",
+		"build",
+		"rebuild"
+	], "switch"],
+	scout: [["scouting", "scout"], "off"]
+};
+/** Of what a layer gives, the lists that add to the lower layers' rather than replace them */
+var ADDED = /* @__PURE__ */ new Set(["plans.build.wants", "waves.groups"]);
+/** Of what a layer gives, the tables merged key by key with the lower layers' rather than replaced */
+var MERGED = /* @__PURE__ */ new Set([
+	"plans",
+	"plans.build",
+	"plans.production",
+	"plans.build.placement"
+]);
+var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** A copy of a layer with its flags taken into the areas they name, the area's own value of the same layer over it */
+function folded(layer, ai) {
+	const copy = { ...layer };
+	for (const [flag, value] of Object.entries(layer.flags ?? {})) {
+		const where = FLAGGED[flag];
+		if (!where) continue;
+		const said = typeof value === "function" ? ai ? value(ai) : void 0 : value;
+		if (said === void 0) continue;
+		const [path, kind] = where;
+		const word = kind === "switch" ? !!said : kind === "off" ? said === false ? false : void 0 : said;
+		if (word === void 0) continue;
+		let at = copy;
+		for (const key of path.slice(0, -1)) {
+			at[key] = { ...at[key] };
+			at = at[key];
+		}
+		const key = path[path.length - 1];
+		if (at[key] === void 0) at[key] = word;
+	}
+	return copy;
+}
+/** A layer's values over the lower layers', key by key: see `ADDED`, `MERGED`; `true` over a share keeps the share */
+function over(under, given, path) {
+	const merged = { ...under };
+	for (const [key, value] of Object.entries(given)) {
+		if (value === void 0) continue;
+		const at = path ? `${path}.${key}` : key;
+		const below = merged[key];
+		if (ADDED.has(at) && Array.isArray(value)) merged[key] = [...below ?? [], ...value];
+		else if ((MERGED.has(at) || !path) && isObject(value) && isObject(below)) merged[key] = over(below, value, at);
+		else if (value === true && typeof below === "number") continue;
+		else merged[key] = value;
+	}
+	return merged;
+}
+/**
+* The settings layered, lowest first (see the file's comment): each area's values key by key, a flag taken into the area
+* it names in its own layer. A flag that is a function of the brain is asked of `ai`, and left out where none is given
+*
+* @beta
+*/
+function resolveSettings(layers, ai) {
+	let resolved = {};
+	for (const layer of layers) if (layer) resolved = over(resolved, folded(layer, ai), "");
+	for (const [path, kind] of Object.values(FLAGGED)) {
+		if (kind !== "share") continue;
+		const area = resolved[path[0]];
+		if (area?.[path[1]] === true) resolved[path[0]] = {
+			...area,
+			[path[1]]: void 0
+		};
+	}
+	return resolved;
+}
+//#endregion
+//#region src/ai/profiles.ts
+/**
+* The engine's defaults of how well it plays: the bottom layer. The areas' numbers are each area's own where no layer
+* says them (`Economy`'s 8 workers)
+*
+* @beta
+*/
+var DEFAULT_PROFILE = {
+	difficulty: "normal",
+	personality: "balanced",
+	every: 1,
+	mistakes: 0,
+	vision: "fair"
+};
+/** The numbers the strongest difficulties share */
+var STRONG = {
+	every: .5,
+	economy: {
+		workers: 10,
+		expansions: 2
+	},
+	army: {
+		firstAttack: 105,
+		attackEvery: 34,
+		waveSize: 8
+	},
+	defence: { radius: 22 },
+	scouting: { lookEvery: 60 }
+};
+/**
+* The engine's difficulties: how well it plays. `normal` is the areas' own numbers. `insane` sees through the fog and
+* gets half again of what its workers bring in, as the classic insane computer does
+*
+* @beta
+*/
+var DIFFICULTIES = {
+	easy: {
+		every: 2,
+		commandsPerThink: 12,
+		mistakes: .25,
+		economy: {
+			workers: 6,
+			expansions: 0
+		},
+		army: {
+			firstAttack: 240,
+			attackEvery: 70,
+			waveSize: 4
+		},
+		defence: { radius: 10 },
+		scouting: { lookEvery: 150 },
+		heroes: { most: 1 }
+	},
+	normal: {},
+	hard: STRONG,
+	insane: {
+		...STRONG,
+		vision: "all",
+		handicap: { income: 1.5 }
+	}
+};
+/**
+* The engine's personalities: how it likes to play. Over the difficulty, so a rusher rushes on any of them
+*
+* @beta
+*/
+var PERSONALITIES = {
+	balanced: {},
+	rusher: {
+		army: {
+			firstAttack: 90,
+			attackEvery: 30,
+			waveSize: 4
+		},
+		economy: { expansions: 0 },
+		defence: { towers: 0 },
+		weights: {
+			creep: .5,
+			harass: 1.2,
+			expand: .5
+		},
+		flags: { noMercy: true }
+	},
+	turtle: {
+		army: { firstAttack: 300 },
+		defence: {
+			towers: 2,
+			odds: .8
+		},
+		economy: { expansions: 0 },
+		weights: {
+			attack: .8,
+			creep: .6,
+			raid: .5,
+			harass: .2,
+			expand: 1.2
+		},
+		flags: { workersFlee: true }
+	},
+	expander: {
+		economy: {
+			expansions: 3,
+			expandWhen: { all: [{ time: { after: 150 } }, { units: { role: "barracks" } }] }
+		},
+		weights: {
+			attack: .9,
+			expand: 1.5
+		}
+	},
+	harasser: {
+		army: {
+			attackEvery: 30,
+			waveSize: 4
+		},
+		weights: {
+			creep: 1.2,
+			raid: 1.5,
+			harass: 1.5
+		},
+		flags: {
+			kite: true,
+			heroesFlee: .5,
+			noMercy: true
+		}
+	}
+};
+/**
+* The difficulties a game's computers may play at, by name: the engine's, the game's over them
+*
+* @beta
+*/
+function difficultiesOf(registry) {
+	return {
+		...DIFFICULTIES,
+		...registry?.module?.ai?.difficulties
+	};
+}
+/**
+* The personalities a game's computers may have, by name: the engine's, the game's over them
+*
+* @beta
+*/
+function personalitiesOf(registry) {
+	return {
+		...PERSONALITIES,
+		...registry?.module?.ai?.personalities
+	};
+}
+/** What a profile says of how well it plays, beside its settings: layered field by field (the handicap and the budget merged) */
+var HOW_WELL = [
+	"brain",
+	"difficulty",
+	"personality",
+	"every",
+	"commandsPerThink",
+	"mistakes",
+	"vision",
+	"budget",
+	"handicap"
+];
+/** A profile's settings: what is not of how well it plays */
+function settingsOf(profile) {
+	if (!profile) return void 0;
+	const settings = { ...profile };
+	for (const key of HOW_WELL) delete settings[key];
+	return settings;
+}
+/**
+* The profile a seat plays by (`Brain.profile`): the brain's settings (`BrainDef.settings`), the game's defaults, the
+* race's (`GameAi.races`, for the `race` the seat plays), the difficulty, the personality, the seat's own
+* (`AiOptions.settings`, the map's under it), each over the one before; how well it plays from the engine's defaults,
+* the game's, the race's, the difficulty, the personality and the seat's `every` and `budget`. A name the game does not
+* have is passed over, and `unknown` names it
+*
+* @beta
+*/
+function resolveProfile(options, registry, brain, race) {
+	const defaults = registry?.module?.ai?.defaults;
+	const raced = race !== void 0 ? registry?.module?.ai?.races?.[race] : void 0;
+	const difficulty = options.difficulty ?? raced?.difficulty ?? defaults?.difficulty ?? "normal";
+	const personality = options.personality ?? raced?.personality ?? defaults?.personality ?? "balanced";
+	const difficulties = difficultiesOf(registry);
+	const personalities = personalitiesOf(registry);
+	const unknown = [];
+	if (!difficulties[difficulty]) unknown.push(`difficulty "${difficulty}"`);
+	if (!personalities[personality]) unknown.push(`personality "${personality}"`);
+	const seat = {
+		...options.every !== void 0 && { every: options.every },
+		...options.budget !== void 0 && { budget: typeof options.budget === "number" ? { modulesPerTick: options.budget } : options.budget }
+	};
+	const profile = {};
+	for (const each of [
+		DEFAULT_PROFILE,
+		defaults,
+		raced,
+		difficulties[difficulty],
+		personalities[personality],
+		seat
+	]) for (const key of HOW_WELL) {
+		const value = each?.[key];
+		if (value === void 0) continue;
+		profile[key] = key === "budget" || key === "handicap" ? {
+			...profile[key],
+			...value
+		} : value;
+	}
+	profile.difficulty = difficulty;
+	profile.personality = personality;
+	const layers = [
+		brain,
+		settingsOf(defaults),
+		settingsOf(raced),
+		settingsOf(difficulties[difficulty]),
+		settingsOf(personalities[personality]),
+		options.settings
+	].filter((layer) => !!layer);
+	return {
+		profile: {
+			...resolveSettings(layers),
+			...profile
+		},
+		layers,
+		unknown
+	};
+}
+/**
+* A flag's value as asked now: a function of the brain worked out, data as it is. For a flag no area has a name for
+* (No Mercy, Random Paths, Allow Home Changes): the rest are the areas' (`ai.settings`)
+*
+* @beta
+*/
+function flagOf(ai, name) {
+	const value = ai.settings.flags?.[name];
+	return typeof value === "function" ? value(ai) : value;
+}
+//#endregion
+export { flagOf as a, resolveSettings as c, difficultiesOf as i, DIFFICULTIES as n, personalitiesOf as o, PERSONALITIES as r, resolveProfile as s, DEFAULT_PROFILE as t };
+
+//# sourceMappingURL=profiles-B3NS9jwk.js.map

package/dist/profiles-B3NS9jwk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiles-B3NS9jwk.js","names":[],"sources":["../src/ai/settings.ts","../src/ai/profiles.ts"],"sourcesContent":["/**\n * The settings of a brain (design review B2): every number and switch its areas play by, in one schema keyed by area,\n * each under the area's own names (`{ economy: { workers }, defence: { radius, towers }, micro: { unitsFlee } }`). Every\n * layer speaks it, lowest first:\n *\n *   the brain's definition (`BrainDef.settings`)  →  the game's defaults (`GameAi.defaults`)  →  the race's\n *   (`GameAi.races`)  →  the difficulty  →  the personality  →  the map (`MapAi.settings`, `MapAi.races`)  →  the seat\n *   (`AiOptions.settings`)\n *\n * and `resolveSettings` layers them once: an area's values key by key, the higher layer's over the lower's. What a\n * module was made with (`economy({ workers })`) is under all of them, and what no layer says is the area's own default\n * (`Economy`'s 8 workers). An area reads what it plays by from `ai.settings` and nothing else.\n *\n * The classic flags (`AiFlags`) are a section of their own, for a lobby and the editor's flags list: a flag that says what\n * an area has a name for (Kite: `micro.kite`, Units Flee: `micro.unitsFlee`) is taken into that area in the layer that\n * says it, so that a higher layer's word goes over it either way. A flag may be a function of the brain: worked out each\n * think, as `ai.settings` is\n */\nimport type { DefenceOptions } from './defence'\nimport type { EconomyOptions } from './economy'\nimport type { Brain } from './brain'\nimport type { LanesPlayOptions } from './lanes'\nimport type { MeleeArmyOptions } from './melee/goals'\nimport type { MeleeHeroesOptions } from './melee/heroes'\nimport type { MicroOptions } from './micro'\nimport type { PlansOptions } from './plans/plans'\nimport type { AiFlags } from './profiles'\nimport type { ScoutingOptions } from './scouting'\nimport type { SquadsOptions } from './squads'\nimport type { TeamOptions } from './team'\nimport type { WavesOptions } from './waves'\n\n/**\n * What a brain's areas play by, by area, each under its own names (see the file's comment): what every layer gives, from\n * the brain's definition to the seat. Plain data where a lobby, a map or a save holds it; a function in it is code, not\n * kept in a save\n *\n * @beta\n */\nexport interface AiSettings {\n\t/** The workers and the bases (`Economy`) */\n\teconomy?: EconomyOptions\n\t/** What it defends and how (`Defence`) */\n\tdefence?: DefenceOptions\n\t/** How often it looks and with whom (`Scouting`) */\n\tscouting?: ScoutingOptions\n\t/** How its units fight (`Micro`) */\n\tmicro?: MicroOptions\n\t/** How its squads go, and the tasks they may be given (`Squads`) */\n\tsquads?: SquadsOptions\n\t/** How it plays with its team (`Team`) */\n\tteam?: TeamOptions\n\t/** The waves it was given (`Waves`) */\n\twaves?: WavesOptions\n\t/** What it builds, trains and researches, and in what order (`Plans`) */\n\tplans?: PlansOptions\n\t/** The melee army: when it attacks, how many go, how a wave goes (`melee.army`) */\n\tarmy?: MeleeArmyOptions\n\t/** The melee player's heroes: how many, and from when (`melee.heroes`) */\n\theroes?: MeleeHeroesOptions\n\t/** A lanes brain's play (`lanes`) */\n\tlanes?: LanesPlayOptions\n\t/** How much each goal weighs, by its id (1 when left out): the picker's (`Goals`) */\n\tweights?: Record<string, number>\n\t/** The classic flags (see the file's comment) */\n\tflags?: AiFlags\n}\n\n/**\n * Where each flag that an area has a name for goes in it, and whether it is a share (`true`: the share a lower layer or\n * the area gives; a number: that share; `false`: never)\n */\nconst FLAGGED: Readonly<Partial<Record<keyof AiFlags, readonly [path: readonly string[], kind: 'switch' | 'share' | 'off']>>> = {\n\tdefendUsers: [['team', 'defendUsers'], 'switch'],\n\tsay: [['team', 'say'], 'switch'],\n\ttargetHeroes: [['micro', 'targetHeroes'], 'switch'],\n\tignoreInjured: [['micro', 'ignoreInjured'], 'switch'],\n\tremoveInjuries: [['micro', 'removeInjuries'], 'switch'],\n\ttakeItems: [['micro', 'takeItems'], 'switch'],\n\tbuyItems: [['micro', 'buyItems'], 'switch'],\n\tsmartArtillery: [['micro', 'smartArtillery'], 'switch'],\n\tkite: [['micro', 'kite'], 'switch'],\n\tunitsFlee: [['micro', 'unitsFlee'], 'share'],\n\theroesFlee: [['micro', 'heroesFlee'], 'share'],\n\tgroupsFlee: [['squads', 'retreatAt'], 'share'],\n\tworkersFlee: [['economy', 'workersFlee'], 'switch'],\n\trepairStructures: [['plans', 'build', 'repair'], 'switch'],\n\trebuild: [['plans', 'build', 'rebuild'], 'switch'],\n\t// only its no: the scouting's `scout` is who goes, where it is not `false`\n\tscout: [['scouting', 'scout'], 'off']\n}\n\n/** Of what a layer gives, the lists that add to the lower layers' rather than replace them */\nconst ADDED = new Set(['plans.build.wants', 'waves.groups'])\n\n/** Of what a layer gives, the tables merged key by key with the lower layers' rather than replaced */\nconst MERGED = new Set(['plans', 'plans.build', 'plans.production', 'plans.build.placement'])\n\ntype Loose = Record<string, unknown>\n\nconst isObject = (value: unknown): value is Loose => typeof value === 'object' && value !== null && !Array.isArray(value)\n\n/** A copy of a layer with its flags taken into the areas they name, the area's own value of the same layer over it */\nfunction folded(layer: AiSettings, ai: Brain | undefined): Loose {\n\tconst copy: Loose = { ...layer }\n\tfor (const [flag, value] of Object.entries(layer.flags ?? {})) {\n\t\tconst where = FLAGGED[flag as keyof AiFlags]\n\t\tif (!where) continue\n\t\tconst said = typeof value === 'function' ? (ai ? (value as (ai: Brain) => unknown)(ai) : undefined) : value\n\t\tif (said === undefined) continue\n\t\tconst [path, kind] = where\n\t\tconst word = kind === 'switch' ? !!said : kind === 'off' ? (said === false ? false : undefined) : said\n\t\tif (word === undefined) continue\n\t\tlet at = copy\n\t\tfor (const key of path.slice(0, -1)) {\n\t\t\tat[key] = { ...(at[key] as Loose | undefined) }\n\t\t\tat = at[key] as Loose\n\t\t}\n\t\tconst key = path[path.length - 1]\n\t\tif (at[key] === undefined) at[key] = word\n\t}\n\treturn copy\n}\n\n/** A layer's values over the lower layers', key by key: see `ADDED`, `MERGED`; `true` over a share keeps the share */\nfunction over(under: Loose, given: Loose, path: string): Loose {\n\tconst merged: Loose = { ...under }\n\tfor (const [key, value] of Object.entries(given)) {\n\t\tif (value === undefined) continue\n\t\tconst at = path ? `${path}.${key}` : key\n\t\tconst below = merged[key]\n\t\tif (ADDED.has(at) && Array.isArray(value)) merged[key] = [...((below as unknown[] | undefined) ?? []), ...value]\n\t\telse if ((MERGED.has(at) || !path) && isObject(value) && isObject(below)) merged[key] = over(below, value, at)\n\t\telse if (value === true && typeof below === 'number') continue\n\t\telse merged[key] = value\n\t}\n\treturn merged\n}\n\n/**\n * The settings layered, lowest first (see the file's comment): each area's values key by key, a flag taken into the area\n * it names in its own layer. A flag that is a function of the brain is asked of `ai`, and left out where none is given\n *\n * @beta\n */\nexport function resolveSettings(layers: readonly (AiSettings | undefined)[], ai?: Brain): AiSettings {\n\tlet resolved: Loose = {}\n\tfor (const layer of layers) if (layer) resolved = over(resolved, folded(layer, ai), '')\n\t// a share left at `true` is the area's own\n\tfor (const [path, kind] of Object.values(FLAGGED)) {\n\t\tif (kind !== 'share') continue\n\t\tconst area = resolved[path[0]] as Loose | undefined\n\t\tif (area?.[path[1]] === true) resolved[path[0]] = { ...area, [path[1]]: undefined }\n\t}\n\treturn resolved as AiSettings\n}\n","import type { Registry } from '#engine/registry'\nimport type { AiConditionTest } from './rules'\nimport type { ThinkBudgetOptions } from './budget'\nimport type { AiOptions } from './options'\nimport type { Brain } from './brain'\nimport { type AiSettings, resolveSettings } from './settings'\n\n/*\n * Profiles (AI plan, D1): how a computer player plays, as one piece of plain data. A profile (`AiProfile`) is the\n * settings of its areas (`AiSettings`, keyed by area: see settings.ts) and how well it plays, and is made of layers,\n * lowest first:\n *\n *   the brain's  →  the game's defaults  →  the race's  →  the difficulty (by name)  →  the personality (by name)  →  the map  →  the seat\n *\n * - **A race's** (`GameAi.races`, by the race the seat plays) is how the game's computers play that race: its build\n *   order, its heroes, its composition, a flag the race's roster asks for. Under the difficulty and the personality,\n *   so that a hard rusher of either race is still hard and still rushes; the map's (`MapAi.races`) goes over the map's\n *   settings for a player whose race the map leaves to the lobby.\n * - **A difficulty** (`easy`, `normal`, `hard`, `insane`, or a game's own: `GameModule.ai.difficulties`) is how\n *   well it plays: how often it thinks, how many commands a think may send (`commandsPerThink`, a person's hands), how\n *   often it slips (`mistakes`: a think's fights left alone, a wave sent early; drawn with its own numbers, so the same\n *   game slips alike), whether it sees through the fog (`vision: 'all'`, insane only: the one way a computer sees what\n *   its seat does not, an observer's session), and the handicaps it is given (`handicap`: more of what its workers\n *   bring in, more health, more damage, quicker making, asked of the game through its hooks as the computer is seated).\n * - **A personality** (`balanced`, `rusher`, `turtle`, `expander`, `harasser`, or a game's own: `GameModule.ai.personalities`) is how\n *   it likes to play: how much each goal weighs (`weights`), when it attacks and expands, how many towers it puts up.\n * - **The map's and the seat's** are what the map (`MapAi`), the lobby or the mission give (`AiOptions.settings`).\n *\n * `ai.profile` is the profile resolved; `ai.settings` its settings as the areas read them, worked out once a think.\n * Every field is data a lobby, a map or an editor can hold; a flag may be a function of the brain instead (code: given\n * again by the game, not kept in a save).\n */\n\n/**\n * A flag's value: as data, or worked out by the brain as it is asked (code, not kept in a save)\n *\n * @beta\n */\nexport type AiFlag<T> = T | ((ai: Brain) => T)\n\n/**\n * The classic RTS behaviour flags, where the meaning holds, and the kit's own beside them: each a yes or no, a number where\n * one says how much, or a function of the brain\n *\n * @beta\n */\nexport interface AiFlags {\n\t/** Helps its allies, people and computers, where asked (the team's `help` goal) */\n\tdefendUsers?: AiFlag<boolean>\n\t/** Hits heroes first among those alike (the micro's targets) */\n\ttargetHeroes?: AiFlag<boolean>\n\t/** Mends damaged buildings when no enemy reaches them (the build plan's `repair`) */\n\trepairStructures?: AiFlag<boolean>\n\t/** A hero leaves a fight under this share of its health: `true` at the share under it, `false` never (`micro.heroesFlee`) */\n\theroesFlee?: AiFlag<boolean | number>\n\t/** A unit leaves a fight under this share of its health: `true` at the share under it, `false` never (`micro.unitsFlee`) */\n\tunitsFlee?: AiFlag<boolean | number>\n\t/** A squad falls back from a fight away from home under these odds: `true` at the odds under it, `false` never (`squads.retreatAt`) */\n\tgroupsFlee?: AiFlag<boolean | number>\n\t/** Attacks before its time when the enemy's army as last seen is weak against its own: at these odds (`true`: 0.75) */\n\tnoMercy?: AiFlag<boolean | number>\n\t/** A unit that fled stays out until healed */\n\tignoreInjured?: AiFlag<boolean>\n\t/** The hurt go home to heal between fights */\n\tremoveInjuries?: AiFlag<boolean>\n\t/** Picks up what lies about */\n\ttakeItems?: AiFlag<boolean>\n\t/** Its heroes buy from shops in reach */\n\tbuyItems?: AiFlag<boolean>\n\t/** Builds its hall again where it can, once its home falls, rather than where it first stood: yes when left out */\n\tallowHomeChanges?: AiFlag<boolean>\n\t/** Siege units shoot buildings and stay behind their squad */\n\tsmartArtillery?: AiFlag<boolean>\n\t/** Each wave takes a way of its own to the target, by the brain's numbers: straight, or round one side or the other */\n\trandomPaths?: AiFlag<boolean>\n\t/** Builds again what it lost */\n\trebuild?: AiFlag<boolean>\n\t/** Ranged units step back from melee they outrun */\n\tkite?: AiFlag<boolean>\n\t/** Workers a raid is on walk to a safe base */\n\tworkersFlee?: AiFlag<boolean>\n\t/** Says its lines to its side (the team's `say`) */\n\tsay?: AiFlag<boolean>\n\t/** Sends a unit to look at the enemy (the scouting's goal) */\n\tscout?: AiFlag<boolean>\n}\n\n/**\n * How a computer player plays, as plain data: the settings of its areas (`AiSettings`) and how well it plays, every field\n * optional, layered (see the file's comment). What a difficulty, a personality and a game's defaults give\n *\n * @beta\n */\nexport interface AiProfile extends AiSettings {\n\t/**\n\t * The brain it plays with, by id (one the game lists in `GameModule.brains`): what a race's profile says\n\t * (`GameAi.races`, campaign plan AR3), for a seat that names none and a map that says none. The game's first brain\n\t * where nothing says\n\t */\n\tbrain?: string\n\t/** The difficulty by name: `easy`, `normal`, `hard`, `insane`, or a game's own (`GameModule.ai.difficulties`). `normal` when left out */\n\tdifficulty?: string\n\t/** The personality by name: `balanced`, `rusher`, `turtle`, `expander`, `harasser`, or a game's own. `balanced` when left out */\n\tpersonality?: string\n\t/** Seconds between thinks: its reactions */\n\tevery?: number\n\t/** Commands a think may send at the most, like a person's hands: no limit when left out */\n\tcommandsPerThink?: number\n\t/** How often it slips, 0 to 1: a think's fights left alone, a wave sent early. Drawn with the brain's own numbers */\n\tmistakes?: number\n\t/** `fair`: it sees what its seat does. `all`: it sees through the fog (an observer's session), for insane only */\n\tvision?: 'fair' | 'all'\n\t/**\n\t * How much of a think one tick may do (`ThinkBudgetOptions`): modules a tick, units looked at a tick, the milliseconds\n\t * a module is warned over (4). Nothing sliced when left out: a game sets it where its numbers ask, at many computers\n\t */\n\tbudget?: ThinkBudgetOptions\n\t/**\n\t * What it is given beyond the rules, each a factor (1 is none), through the game's hooks while it is seated:\n\t * `income`, what its workers bring in (1.5: half again; `beforeDeposit`); `health`, the most health of everything\n\t * it has (`stats`); `damage`, the damage it deals (`beforeDamage`, before armour); `buildTime`, how long what it\n\t * trains, builds and researches takes (0.8: a fifth sooner; `beforeProduce`). The classic handicap is `health`\n\t */\n\thandicap?: AiHandicap\n}\n\n/**\n * What a computer is given beyond the rules (`AiProfile.handicap`): each a factor, 1 (or left out) for none\n *\n * @beta\n */\nexport interface AiHandicap {\n\t/** What its workers bring in, through the game's `beforeDeposit` hook */\n\tincome?: number\n\t/** The most health of everything it has, through a `stats` hook: the classic handicap */\n\thealth?: number\n\t/** The damage it deals, before armour, through a `beforeDamage` hook */\n\tdamage?: number\n\t/** How long what it trains, builds and researches takes, through a `beforeProduce` hook: under 1 is sooner */\n\tbuildTime?: number\n}\n\n/**\n * A difficulty's or a personality's profile, the engine's or a game's\n *\n * @beta\n */\nexport type AiProfileTable = Record<string, AiProfile>\n\n/**\n * The engine's defaults of how well it plays: the bottom layer. The areas' numbers are each area's own where no layer\n * says them (`Economy`'s 8 workers)\n *\n * @beta\n */\nexport const DEFAULT_PROFILE: Readonly<AiProfile> = {\n\tdifficulty: 'normal',\n\tpersonality: 'balanced',\n\tevery: 1,\n\tmistakes: 0,\n\tvision: 'fair'\n}\n\n/** The numbers the strongest difficulties share */\nconst STRONG: AiProfile = {\n\tevery: 0.5,\n\teconomy: { workers: 10, expansions: 2 },\n\tarmy: { firstAttack: 105, attackEvery: 34, waveSize: 8 },\n\tdefence: { radius: 22 },\n\tscouting: { lookEvery: 60 }\n}\n\n/**\n * The engine's difficulties: how well it plays. `normal` is the areas' own numbers. `insane` sees through the fog and\n * gets half again of what its workers bring in, as the classic insane computer does\n *\n * @beta\n */\nexport const DIFFICULTIES: Readonly<AiProfileTable> = {\n\teasy: {\n\t\tevery: 2,\n\t\tcommandsPerThink: 12,\n\t\tmistakes: 0.25,\n\t\teconomy: { workers: 6, expansions: 0 },\n\t\tarmy: { firstAttack: 240, attackEvery: 70, waveSize: 4 },\n\t\tdefence: { radius: 10 },\n\t\tscouting: { lookEvery: 150 },\n\t\theroes: { most: 1 }\n\t},\n\tnormal: {},\n\thard: STRONG,\n\tinsane: { ...STRONG, vision: 'all', handicap: { income: 1.5 } }\n}\n\n/**\n * The engine's personalities: how it likes to play. Over the difficulty, so a rusher rushes on any of them\n *\n * @beta\n */\nexport const PERSONALITIES: Readonly<AiProfileTable> = {\n\tbalanced: {},\n\trusher: {\n\t\tarmy: { firstAttack: 90, attackEvery: 30, waveSize: 4 },\n\t\teconomy: { expansions: 0 },\n\t\tdefence: { towers: 0 },\n\t\tweights: { creep: 0.5, harass: 1.2, expand: 0.5 },\n\t\tflags: { noMercy: true }\n\t},\n\tturtle: {\n\t\tarmy: { firstAttack: 300 },\n\t\tdefence: { towers: 2, odds: 0.8 },\n\t\teconomy: { expansions: 0 },\n\t\tweights: { attack: 0.8, creep: 0.6, raid: 0.5, harass: 0.2, expand: 1.2 },\n\t\tflags: { workersFlee: true }\n\t},\n\texpander: {\n\t\teconomy: { expansions: 3, expandWhen: { all: [{ time: { after: 150 } }, { units: { role: 'barracks' } }] } },\n\t\tweights: { attack: 0.9, expand: 1.5 }\n\t},\n\tharasser: {\n\t\tarmy: { attackEvery: 30, waveSize: 4 },\n\t\tweights: { creep: 1.2, raid: 1.5, harass: 1.5 },\n\t\tflags: { kite: true, heroesFlee: 0.5, noMercy: true }\n\t}\n}\n\n/**\n * What a game says of its computer players' profiles (`GameModule.ai`): difficulties and personalities of its own, and\n * defaults over the engine's\n *\n * @beta\n */\nexport interface GameAi {\n\t/** Difficulties of its own, by name, beside (or over) the engine's */\n\tdifficulties?: AiProfileTable\n\t/** Personalities of its own, by name */\n\tpersonalities?: AiProfileTable\n\t/** Conditions of its own, by id, for the data form (`{ is: 'mygame.bridgeDown', args }`), a map's file among them */\n\tconditions?: Record<string, AiConditionTest>\n\t/** Defaults over the engine's, under the difficulty */\n\tdefaults?: AiProfile\n\t/**\n\t * How its computers play each of its races (`GameModule.races`), by race id: a layer over `defaults` and under the\n\t * difficulty, for a seat of that race (its build order, heroes, composition, flags; how often it thinks). Its\n\t * `difficulty` and `personality` are the seat's where the lobby and the map say none\n\t */\n\traces?: AiProfileTable\n\t/** Whether a lobby offers its seats a difficulty and a personality (`seatSettingsOf`): yes when left out */\n\tlobby?: boolean\n}\n\n/**\n * The difficulties a game's computers may play at, by name: the engine's, the game's over them\n *\n * @beta\n */\nexport function difficultiesOf(registry?: Pick<Registry, 'module'>): AiProfileTable {\n\treturn { ...DIFFICULTIES, ...registry?.module?.ai?.difficulties }\n}\n\n/**\n * The personalities a game's computers may have, by name: the engine's, the game's over them\n *\n * @beta\n */\nexport function personalitiesOf(registry?: Pick<Registry, 'module'>): AiProfileTable {\n\treturn { ...PERSONALITIES, ...registry?.module?.ai?.personalities }\n}\n\n/** What a profile says of how well it plays, beside its settings: layered field by field (the handicap and the budget merged) */\nconst HOW_WELL = ['brain', 'difficulty', 'personality', 'every', 'commandsPerThink', 'mistakes', 'vision', 'budget', 'handicap'] as const\n\n/**\n * A profile resolved (`resolveProfile`): what it plays by, and its settings' layers as given, lowest first, for the brain\n * to work out each think (a flag may be a function of it)\n *\n * @beta\n */\nexport interface ResolvedProfile {\n\t/** The profile, its settings layered (a flag's function left out) */\n\tprofile: AiProfile\n\t/** Its settings' layers, lowest first: the brain's, the game's, the race's, the difficulty's, the personality's, the seat's (the map's under it) */\n\tlayers: readonly AiSettings[]\n\t/** A difficulty or a personality the game does not have, passed over */\n\tunknown: string[]\n}\n\n/** A profile's settings: what is not of how well it plays */\nfunction settingsOf(profile: AiProfile | undefined): AiSettings | undefined {\n\tif (!profile) return undefined\n\tconst settings: Record<string, unknown> = { ...profile }\n\tfor (const key of HOW_WELL) delete settings[key]\n\treturn settings as AiSettings\n}\n\n/**\n * The profile a seat plays by (`Brain.profile`): the brain's settings (`BrainDef.settings`), the game's defaults, the\n * race's (`GameAi.races`, for the `race` the seat plays), the difficulty, the personality, the seat's own\n * (`AiOptions.settings`, the map's under it), each over the one before; how well it plays from the engine's defaults,\n * the game's, the race's, the difficulty, the personality and the seat's `every` and `budget`. A name the game does not\n * have is passed over, and `unknown` names it\n *\n * @beta\n */\nexport function resolveProfile(options: AiOptions, registry?: Pick<Registry, 'module'>, brain?: AiSettings, race?: string): ResolvedProfile {\n\tconst defaults = registry?.module?.ai?.defaults\n\tconst raced = race !== undefined ? registry?.module?.ai?.races?.[race] : undefined\n\tconst difficulty = options.difficulty ?? raced?.difficulty ?? defaults?.difficulty ?? 'normal'\n\tconst personality = options.personality ?? raced?.personality ?? defaults?.personality ?? 'balanced'\n\tconst difficulties = difficultiesOf(registry)\n\tconst personalities = personalitiesOf(registry)\n\tconst unknown: string[] = []\n\tif (!difficulties[difficulty]) unknown.push(`difficulty \"${difficulty}\"`)\n\tif (!personalities[personality]) unknown.push(`personality \"${personality}\"`)\n\tconst seat: AiProfile = {\n\t\t...(options.every !== undefined && { every: options.every }),\n\t\t...(options.budget !== undefined && { budget: typeof options.budget === 'number' ? { modulesPerTick: options.budget } : options.budget })\n\t}\n\tconst profile: Record<string, unknown> = {}\n\tfor (const each of [DEFAULT_PROFILE, defaults, raced, difficulties[difficulty], personalities[personality], seat])\n\t\tfor (const key of HOW_WELL) {\n\t\t\tconst value = each?.[key]\n\t\t\tif (value === undefined) continue\n\t\t\tprofile[key] = key === 'budget' || key === 'handicap' ? { ...(profile[key] as object | undefined), ...(value as object) } : value\n\t\t}\n\tprofile.difficulty = difficulty\n\tprofile.personality = personality\n\tconst layers = [\n\t\tbrain,\n\t\tsettingsOf(defaults),\n\t\tsettingsOf(raced),\n\t\tsettingsOf(difficulties[difficulty]),\n\t\tsettingsOf(personalities[personality]),\n\t\toptions.settings\n\t].filter((layer): layer is AiSettings => !!layer)\n\treturn { profile: { ...resolveSettings(layers), ...(profile as AiProfile) }, layers, unknown }\n}\n\n/**\n * A flag's value as asked now: a function of the brain worked out, data as it is. For a flag no area has a name for\n * (No Mercy, Random Paths, Allow Home Changes): the rest are the areas' (`ai.settings`)\n *\n * @beta\n */\nexport function flagOf<K extends keyof AiFlags>(ai: Brain, name: K): Exclude<AiFlags[K], (ai: Brain) => unknown> | undefined {\n\tconst value = ai.settings.flags?.[name]\n\treturn (typeof value === 'function' ? (value as (ai: Brain) => unknown)(ai) : value) as Exclude<AiFlags[K], (ai: Brain) => unknown> | undefined\n}\n"],"mappings":"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"}

package/dist/races.d.ts

@@ -0,0 +1,136 @@
+import type { ResourceKind } from './defs';
+import { type PlayerId } from './entity';
+import type { GameModule } from './game';
+import type { HookDef } from './hooks';
+import type { Player } from './player';
+import type { Registry } from './registry';
+import { type StartDef } from './start';
+import type { World } from './world';
+/**
+ * A side a player can play, with a roster of its own: melee's humans and undead. Optional: a game that lists none
+ * (`GameModule.races`) has no race anywhere, no choice of one in the lobby and nothing kept from anyone. A unit type or
+ * an upgrade of a race (`UnitTypeDef.race`, `UpgradeDef.race`) is only its players' to make; one of none, everyone's.
+ * Each player has one (`raceOf`): chosen in the lobby (a seat setting the server offers by itself, `seatSettingsOf`),
+ * given to the world as it is made (`PlayerInit.race`, `MapWorldOptions.races`), or changed by the rules (`setRace`)
+ *
+ * @beta
+ */
+export interface RaceDef {
+    id: string;
+    /** What players are shown: in the lobby, on the scores */
+    name: string;
+    /**
+     * The definition this one is a copy of, made from the data (`copyOf` in a `data.json`, the editor's Copy as new):
+     * what it is drawn, heard and pictured as where the game gives it no look of its own
+     */
+    basedOn?: string;
+    /** What it is like, for a tooltip */
+    description?: string;
+    /** Its picture, by the id the game's view knows icons by */
+    icon?: string;
+    /**
+     * What its players start with of each resource, by resource id, over what the game starts everyone with
+     * (`ResourceDef.start`). Not for a player given resources of their own (`PlayerInit.resources`, a map's)
+     */
+    resources?: Partial<Record<ResourceKind, number>>;
+    /**
+     * What its players get at the start of a game on a map, in place of the game's (`GameModule.start`): its own hall and
+     * workers, as data (`StartData`: what a race made in the Data panel has, `start.hall` and the rest editable there)
+     * or as code (`StartCode`)
+     */
+    start?: StartDef;
+    /**
+     * Run for each of its players once a world is made from a map, after everything the map puts down and the starts:
+     * what its players begin with that is not a unit (a ground of its own around its halls, a state)
+     */
+    onStart?(world: World, player: PlayerId): void;
+    /**
+     * Hook handlers of its own, run only for what is of its players (`RaceHookDef`): how it gathers, where it may build.
+     * With these a race plays differently with no test of the race in the game's code
+     */
+    hooks?: RaceHookDef[];
+    /**
+     * What a race made as a copy of another (`basedOn`: `copyOf` in a `data.json`, the editor's Copy as new) keeps of the
+     * original's code: its `hooks` and its `onStart`, each kept unless said `false` here. A copy keeps both when this is
+     * left out, so a race copied from the undead gathers at a cursed mine and builds on blight as they do; one that
+     * says `hooks: false` plays by the game's rules alone. Its `start` is data, the copy's own to change; a `start` in
+     * code is kept whole. Two toggles in the Data panel, on a copy
+     */
+    inherits?: {
+        hooks?: boolean;
+        onStart?: boolean;
+    };
+}
+/**
+ * A hook handler of a race (`RaceDef.hooks`): run only where the event is of one of the race's players. Whose an event
+ * is, is `of(event)` where it is given, or else its `player`, or else the owner of the first there is of its `entity`,
+ * `caster`, `attacker`, `worker`, `buyer`, `hero`, `producer`, `source`, `target`: the one doing it before the one it
+ * is done to (a damage is its source's)
+ *
+ * @beta
+ */
+export type RaceHookDef = HookDef & {
+    /** The player an event is of, where it is not the one found by default */
+    of?: (event: any) => PlayerId | undefined;
+};
+/** The player a hook's event is of (see `RaceHookDef`): undefined for one of nobody's */
+export declare function playerOfEvent(event: unknown): PlayerId | undefined;
+/** Each race's hook handlers, each to run only for what is of the race's players */
+export declare function raceHooks(game: GameModule): HookDef[];
+/**
+ * A race, as the game lists it (`GameModule.races`)
+ *
+ * @beta
+ */
+export declare const defineRace: (def: RaceDef) => RaceDef;
+/**
+ * What is chosen for a seat or a player to have a race drawn for them as the game starts, from the world's own
+ * numbers: the same on every machine
+ *
+ * @beta
+ */
+export declare const RANDOM_RACE = "random";
+/**
+ * The race a player plays: none in a game without races, and none for the neutral players and the creeps
+ *
+ * @beta
+ */
+export declare const raceOf: (world: World, player: PlayerId) => string | undefined;
+/**
+ * Makes a player play another race from now on: a campaign's mission, a game's own way of choosing. What they have
+ * stays theirs; what they may make is the new race's. Throws for a race the game does not have, or for the neutral
+ * players and the creeps
+ *
+ * @beta
+ */
+export declare function setRace(world: World, player: PlayerId, race: string): void;
+/**
+ * Whether a player may make a unit type or research an upgrade at all, as their race goes (`UnitTypeDef.race`), and
+ * then as the game's `available` hook says: what they may not is not on their buttons, and an order for it is
+ * refused. What it requires is another question (`unlocked`), asked only of what is available
+ *
+ * @beta
+ */
+export declare function isAvailable(world: World, player: PlayerId, kind: 'unit' | 'upgrade', id: string): boolean;
+/**
+ * The races players get as a world is made: what each was given, one drawn for those given `random`, and the game's
+ * first for a player given none. Nobody's in a game without races. Throws for a race the game does not have
+ */
+export declare function settleRaces(players: Iterable<Player>, registry: Registry, draw: (count: number) => number, among?: readonly string[]): void;
+/**
+ * Throws for races that cannot be: one there twice, one called `random`, a unit type or upgrade of a race the game does
+ * not have, a resource a race starts with that the game has not, or a start as data (a race's, or the game's) that names
+ * a unit type the game has not, saying which was meant where one is close. Run as a registry is made (`createRegistry`,
+ * every world's); for a game's own tests
+ *
+ * @beta
+ */
+export declare function checkRaces(game: GameModule): void;
+/**
+ * Gives each player of a world just made what their race starts them with (`RaceDef.resources`), but those given
+ * resources of their own
+ */
+export declare function raceResources(world: World, players: readonly {
+    id: PlayerId;
+    resources?: unknown;
+}[]): void;

package/dist/randomGroups.d.ts

@@ -0,0 +1,2 @@
+/** What a thing placed on a map drops when it dies: one item from its table, on the ground where it fell */
+export declare const dropFromTable: import("./events").ListenerDef;