@v12-engine/engine 0.1.1 → 0.4.0

package/dist/commands.js

@@ -0,0 +1,636 @@
+import { atan2 } from "./exactMath.js";
+import { distSq } from "./math.js";
+import { statsOf } from "./stats.js";
+import { commandHandled, commandRejected, constructionCancelled } from "./engineEvents.js";
+import { replicateEvent } from "./replication.js";
+import { constructionSite, underConstruction } from "./systems/construction.js";
+import { fighting, moving } from "./entity.js";
+import { giveBack } from "./player.js";
+import { productionOf } from "./systems/productionQueue.js";
+import { isStunned } from "./abilities/buffs.js";
+import { joinFormation } from "./systems/movement.js";
+import { canAttack } from "./systems/combat.js";
+import { dashing } from "./dashing.js";
+import { steerMissile } from "./abilities/effects.js";
+import { CINEMATIC_OUTCOMES, cinematicChose, cinematicEnded } from "./cinematics.js";
+import { Invalid, bool, id, ids, index, number, object, oneOf, optional, point, string } from "./fields.js";
+import { cameraCommandFields, cameraCommanded } from "./cameraOrders.js";
+import { aimKind } from "./targeting.js";
+import { formationPoints } from "./formation.js";
+import { createOrder, giveOrder, interrupt } from "./orders/queue.js";
+import { castAside, notReady } from "./orders/cast.js";
+import { cancelProduction, enqueueMorph, enqueueProduction, enqueueResearch } from "./systems/production.js";
+import { smartOrder } from "./smart.js";
+import { chat, ping } from "./talk.js";
+import { give, shareWith } from "./trade.js";
+import { askPause, surrender } from "./endings.js";
+import { runOrder } from "./systems/orders.js";
+//#region src/commands.ts
+/**
+* Defines a command type, for a game module's `commands`: its type, its fields (see `fields.ts`), and what it does.
+* `command` is typed by the fields.
+*
+* ```ts
+* const sellTower = defineCommand('sellTower', { tower: id }, (world, player, command) => { ... })
+* session.send(sellTower.make({ tower: 12 }))
+* ```
+*
+* @public
+*/
+function defineCommand(type, fields, execute, options = {}) {
+	for (const own of [
+		"type",
+		"player",
+		"seq"
+	]) if (own in fields) throw new Error(`Command "${type}": "${own}" is what every command carries (who sent it, and the like), name the field otherwise`);
+	return {
+		type,
+		fields,
+		execute,
+		...options.outsideTick && { outsideTick: true },
+		make: (values) => ({
+			...values,
+			type
+		})
+	};
+}
+/** Part of the cost returned when a construction site is cancelled */
+/** The buildings something is to be made in: the selected ones, of which the least busy gets it. `building` for just one */
+/** @internal */
+var producers = {
+	building: optional(id),
+	buildings: optional(ids)
+};
+/**
+* Of the player's buildings that were named, the one that will get to something first: finished, able to make it,
+* and with the shortest queue that has room. As in classic RTS games, a group of barracks shares the work. When none has
+* room, the first that could make it, which then says its queue is full
+*
+* @internal
+*/
+function leastBusy(world, player, command, fits) {
+	const named = [...command.building !== void 0 ? [command.building] : [], ...command.buildings ?? []];
+	let best;
+	let first;
+	for (const entity of owned(world, player, named)) {
+		const production = productionOf(entity);
+		if (!production || !entity.operational || !fits(entity)) continue;
+		first ??= entity;
+		const length = production.queue.length;
+		if (length < world.settings.production.queue && (!best || length < productionOf(best).queue.length)) best = entity;
+	}
+	return best ?? first;
+}
+/**
+* The units a command names that the player may command: their own, and what another shares control of with them
+* (`world.mayCommand`). One of another's, or one there never was, is what their own client never sends: it is
+* turned away (`commandRejected`), and the rest goes on. One that has died meanwhile is let be
+*
+* @internal
+*/
+function owned(world, player, ids) {
+	const result = [];
+	for (const id of ids) {
+		const entity = world.get(id);
+		if (entity && world.mayCommand(player, entity)) result.push(entity);
+		else if (entity) world.events.emit(commandRejected, {
+			player,
+			kind: "notTheirs",
+			reason: `unit ${id} is not theirs`
+		});
+		else if (!world.made(id)) world.events.emit(commandRejected, {
+			player,
+			kind: "noSuchUnit",
+			reason: `there is no unit ${id}`
+		});
+	}
+	return result;
+}
+/** Direction from the middle of a group to where it was sent, so the whole group ends up facing the same way */
+function travelDirection(entities, point) {
+	let x = 0;
+	let z = 0;
+	for (const entity of entities) {
+		x += entity.pos.x;
+		z += entity.pos.z;
+	}
+	x = point.x - x / entities.length;
+	z = point.z - z / entities.length;
+	return x * x + z * z > .04 ? atan2(x, z) : void 0;
+}
+/**
+* Entity a player may point at: one their team sees, a structure they have seen before, or, on a map explored from
+* the start, a structure of nobody's (a tree, a mine). Commands naming anything else are probing for what the player
+* cannot know.
+*
+* @internal
+*/
+function known(world, player, id) {
+	const entity = world.get(id);
+	if (!entity) return void 0;
+	const { team } = world.player(player);
+	if (world.areAllies(entity.owner, player) || world.isVisibleTo(entity, team)) return entity;
+	if (!entity.isStructure) return void 0;
+	if (world.sight.hasSeen(entity, team)) return entity;
+	const owner = world.players.get(entity.owner);
+	return world.fog.exploredFromStart && (owner?.neutral || owner?.creeps) ? entity : void 0;
+}
+/** What a unit is told to do, as a command carries it. See `OrderInit` */
+var orderInit = object({
+	type: string,
+	target: optional(id),
+	point: optional(point),
+	unitType: optional(string),
+	ability: optional(string),
+	item: optional(index),
+	facing: optional(number),
+	path: optional(string),
+	towards: optional(oneOf("first", "last")),
+	formation: optional(string),
+	together: optional(bool)
+});
+/**
+* The engine's `order` command: gives an order to entities the player owns, replacing theirs or queued after them
+*
+* @internal
+*/
+var orderCommand = defineCommand("order", {
+	entities: ids,
+	order: orderInit,
+	queue: optional(bool)
+}, (world, player, { entities: chosen, order: init, queue = false }) => {
+	if (!world.registry.orders.has(init.type)) return;
+	if (init.target && !known(world, player, init.target)) return;
+	const behavior = world.registry.order(init.type);
+	let entities = owned(world, player, chosen).filter((entity) => !entity.has(constructionSite) && behavior.accepts(world, entity, init));
+	if (init.type === "cast" && init.item !== void 0 && !queue) entities = entities.filter((entity) => !castAside(world, entity, init));
+	if (init.type === "attack" && init.target !== void 0 && !queue) entities = entities.filter((entity) => {
+		const current = entity.orders[0];
+		if (current?.type !== "attack" || current.init.target !== init.target) return true;
+		entity.keepOrders(1);
+		return false;
+	});
+	if (entities.length === 0) return;
+	const groupId = world.newId();
+	const facing = init.facing ?? (init.point && !init.target ? travelDirection(entities, init.point) : void 0);
+	const points = /* @__PURE__ */ new Map();
+	if (behavior.formation && init.point && !init.target && entities.length > 1) {
+		const id = init.formation ?? world.settings.movement.formation(world, entities, init);
+		const formation = world.registry.formations.has(id) ? world.registry.formation(id) : world.registry.formation(world.settings.movement.formation(world, entities, init));
+		const flyers = entities.filter((entity) => entity.flying);
+		const walkers = entities.filter((entity) => !entity.flying);
+		for (const [id, point] of formationPoints(world, walkers, init.point, formation, init.facing)) points.set(id, point);
+		for (const [id, point] of formationPoints(world, flyers, init.point, formation, init.facing)) points.set(id, point);
+	}
+	const speedCap = init.type === "move" && !init.target && entities.length > 1 && (init.together ?? false) ? Math.min(...entities.map((entity) => statsOf(world, entity).moveSpeed)) : void 0;
+	for (const entity of entities) {
+		const point = points.get(entity.id) ?? init.point;
+		giveOrder(world, entity, createOrder(world, {
+			...init,
+			point,
+			facing,
+			...speedCap !== void 0 && { speedCap }
+		}, groupId), queue);
+		if (points.has(entity.id) && entity.orders.at(-1)?.groupId === groupId) joinFormation(entity, groupId);
+	}
+});
+/**
+* The engine's `rally` command: sets where the units a building makes go, a point or an entity
+*
+* @internal
+*/
+var rallyCommand = defineCommand("rally", {
+	buildings: ids,
+	point,
+	target: optional(id)
+}, (world, player, command) => {
+	const target = known(world, player, command.target);
+	for (const building of owned(world, player, command.buildings)) {
+		const production = productionOf(building);
+		if (!production) continue;
+		if (target === building) production.rally = null;
+		else production.rally = {
+			point: {
+				x: command.point.x,
+				z: command.point.z
+			},
+			target: target?.id ?? 0
+		};
+	}
+});
+/**
+* The right-click: every unit does what makes sense for it, buildings set their rally point
+*
+* @internal
+*/
+var smartCommand = defineCommand("smart", {
+	entities: ids,
+	point,
+	target: optional(id),
+	queue: optional(bool),
+	formation: optional(string),
+	facing: optional(number)
+}, (world, player, { point, queue, formation, facing, ...command }) => {
+	const target = known(world, player, command.target);
+	const entities = owned(world, player, command.entities);
+	const units = entities.filter((entity) => entity.get(moving));
+	if (units.length === 0) {
+		rallyCommand.execute(world, player, {
+			buildings: entities.map((entity) => entity.id),
+			point,
+			target: target?.id
+		});
+		return;
+	}
+	const groups = /* @__PURE__ */ new Map();
+	for (const unit of units) {
+		const order = smartOrder(world, unit, point, target);
+		if (!order) continue;
+		if (formation !== void 0) order.formation = formation;
+		if (facing !== void 0 && !target) order.facing = facing;
+		if (order.type === "move" && world.settings.movement.together) order.together = true;
+		const key = `${order.type}:${order.target ?? ""}`;
+		let group = groups.get(key);
+		if (!group) groups.set(key, group = {
+			order,
+			ids: []
+		});
+		group.ids.push(unit.id);
+	}
+	for (const group of groups.values()) orderCommand.execute(world, player, {
+		entities: group.ids,
+		order: group.order,
+		queue
+	});
+});
+/**
+* Attack the target, for whoever can. Everyone else, or without a target: attack-move to the point
+*
+* @internal
+*/
+var attackCommand = defineCommand("attack", {
+	entities: ids,
+	point,
+	target: optional(id),
+	queue: optional(bool),
+	formation: optional(string)
+}, (world, player, { point, queue, formation, ...command }) => {
+	const target = known(world, player, command.target);
+	const units = owned(world, player, command.entities).filter((entity) => entity.get(moving) || entity.get(fighting));
+	const attackers = target ? units.filter((unit) => canAttack(world, unit, target, true)) : [];
+	if (target && attackers.length) {
+		orderCommand.execute(world, player, {
+			entities: attackers.map((unit) => unit.id),
+			order: {
+				type: "attack",
+				target: target.id
+			},
+			queue
+		});
+		return;
+	}
+	orderCommand.execute(world, player, {
+		entities: units.map((unit) => unit.id),
+		order: {
+			type: "attackMove",
+			point
+		},
+		queue
+	});
+});
+/**
+* Use an ability. Abilities that need a target are cast by one unit, the one that can and is closest
+*
+* @internal
+*/
+var castCommand = defineCommand("cast", {
+	entities: ids,
+	ability: string,
+	point: optional(point),
+	to: optional(point),
+	target: optional(id),
+	queue: optional(bool)
+}, (world, player, command) => {
+	const { queue } = command;
+	if (!world.registry.abilities.has(command.ability)) return;
+	const ability = world.registry.ability(command.ability);
+	const target = known(world, player, command.target);
+	if (command.target && !target) return;
+	const init = {
+		type: "cast",
+		ability: ability.id,
+		target: target?.id,
+		point: command.point,
+		...command.to && { to: command.to }
+	};
+	const kind = aimKind(world.registry, ability);
+	const behavior = world.registry.order("cast");
+	const casters = owned(world, player, command.entities).filter((entity) => behavior.accepts(world, entity, init));
+	if (casters.length === 0) return;
+	const instant = !queue && !ability.castTime && (kind === "none" || kind === "direction");
+	const give = (caster) => {
+		const order = createOrder(world, init);
+		giveOrder(world, caster, order, queue);
+		if (instant && caster.orders[0] === order && !isStunned(world, caster) && !caster.get(dashing)?.pulled) runOrder(world, caster, order, 0);
+	};
+	if (kind === "none") {
+		for (const caster of casters) if (queue) give(caster);
+		else if (!notReady(world, caster, ability) && !castAside(world, caster, { ability: ability.id })) give(caster);
+		return;
+	}
+	const aim = target?.pos ?? command.point;
+	const ready = casters.filter((caster) => !notReady(world, caster, ability));
+	const pool = ready.length ? ready : casters;
+	let best = pool[0];
+	for (const caster of pool) if (aim && distSq(caster.pos, aim) < distSq(best.pos, aim)) best = caster;
+	if (instant && !notReady(world, best, ability) && castAside(world, best, { ability: ability.id }, command.point)) return;
+	give(best);
+});
+/**
+* Turns the player's missiles of an ability that are steered (`EffectFields.steer`) towards a point, as they fly
+* (`steerMissile`): what the screen sends while one is in the air, for where the pointer is
+*
+* @beta
+*/
+var steerCommand = defineCommand("steer", {
+	ability: string,
+	point
+}, (world, player, command) => {
+	for (const missile of world.missiles) if (missile.owner === player && missile.ability === command.ability) steerMissile(world, missile, command.point);
+});
+/**
+* The engine's `autocast` command: turns an ability's autocast on or off for the entities named
+*
+* @internal
+*/
+var autocastCommand = defineCommand("autocast", {
+	entities: ids,
+	ability: string,
+	enabled: bool
+}, (world, player, command) => {
+	for (const entity of owned(world, player, command.entities)) {
+		const state = entity.abilities.find((ability) => ability.id === command.ability);
+		if (state) state.autocast = command.enabled;
+	}
+});
+/**
+* Stops what units are doing, as the classic Stop does: a plain interrupt. They fight what comes near again at once; a
+* unit that is to stand down and take no fights is put in a stance (`stanceCommand`, `stancesPack`)
+*
+* @beta
+*/
+var stopCommand = defineCommand("stop", { entities: ids }, (world, player, command) => {
+	for (const entity of owned(world, player, command.entities)) interrupt(world, entity);
+});
+/**
+* The engine's `train` command: queues a unit type at the least busy building that can train it
+*
+* @internal
+*/
+var trainCommand = defineCommand("train", {
+	...producers,
+	unitType: string
+}, (world, player, command) => {
+	const building = leastBusy(world, player, command, (entity) => !!entity.def.trains?.includes(command.unitType));
+	if (building) enqueueProduction(world, building, command.unitType);
+});
+/**
+* The engine's `research` command: queues an upgrade at the least busy building that can research it
+*
+* @internal
+*/
+var researchCommand = defineCommand("research", {
+	...producers,
+	upgrade: string
+}, (world, player, command) => {
+	const building = leastBusy(world, player, command, (entity) => !!entity.def.researches?.includes(command.upgrade));
+	if (building) enqueueResearch(world, building, command.upgrade);
+});
+/**
+* Upgrades a building into a type it can become: `into`, one of its `upgradesTo`, or the first where none is named
+*
+* @internal
+*/
+var upgradeBuildingCommand = defineCommand("upgradeBuilding", {
+	building: id,
+	into: optional(string)
+}, (world, player, command) => {
+	const [building] = owned(world, player, [command.building]);
+	if (building) enqueueMorph(world, building, command.into);
+});
+/**
+* The engine's `cancelTrain` command: takes the item at an index out of a building's queue
+*
+* @internal
+*/
+var cancelTrainCommand = defineCommand("cancelTrain", {
+	building: id,
+	index
+}, (world, player, command) => {
+	const [building] = owned(world, player, [command.building]);
+	if (building) cancelProduction(world, building, command.index);
+});
+/**
+* The engine's `cancelConstruction` command: stops a building under construction, refunds part of its cost and removes it
+*
+* @internal
+*/
+var cancelConstructionCommand = defineCommand("cancelConstruction", { building: id }, (world, player, command) => {
+	const [building] = owned(world, player, [command.building]);
+	const site = building && underConstruction(building);
+	if (!site) return;
+	giveBack(world, player, site.paid ?? building.def.cost, world.settings.production.cancelRefund, "structure", building.def.id);
+	world.events.emit(constructionCancelled, building);
+	world.kill(building, void 0, false, "cancelled");
+});
+/** The player skips the line of dialog they hear: a conversation goes on to its next line. See `world.dialog` */
+var skipLineCommand = defineCommand("skipLine", {}, (world, player) => world.dialog.skip(player));
+/** A player marks a spot of the map for their allies: `look`, `danger`, `assist` or `onMyWay` (see `ping`) */
+var pingCommand = defineCommand("ping", {
+	point,
+	kind: optional(string),
+	to: optional(string),
+	by: optional(string)
+}, (world, player, command) => ping(world, player, command.point, command.kind, command.to, command.by), { outsideTick: true });
+/** A player says a line of chat: to `allies` (when left out), or to `all` (see `chat`) */
+var chatCommand = defineCommand("chat", {
+	text: string,
+	to: optional(string),
+	by: optional(string)
+}, (world, player, command) => chat(world, player, command.text, command.to, command.by), { outsideTick: true });
+/** A player gives an ally some of a resource they have (see `give`) */
+var giveCommand = defineCommand("give", {
+	to: id,
+	resource: string,
+	amount: number
+}, (world, player, command) => give(world, player, command.to, command.resource, command.amount));
+/** A player shares control of their units, or their team's sight, with an ally, or no longer (see `shareWith`) */
+var shareCommand = defineCommand("share", {
+	with: id,
+	vision: optional(bool),
+	control: optional(bool)
+}, (world, player, command) => shareWith(world, player, command.with, {
+	vision: command.vision,
+	control: command.control
+}));
+/**
+* A player gives up: out of the game, as if beaten (see `surrender`)
+*
+* @internal
+*/
+var surrenderCommand = defineCommand("surrender", {}, (world, player) => surrender(world, player));
+/**
+* A player asks for the game to be paused, one of their pauses (see `askPause`): whoever runs it pauses it
+*
+* @internal
+*/
+var pauseCommand = defineCommand("pause", {}, (world, player) => askPause(world, player));
+/**
+* A player's own screen says something of its camera (see `cameraFor`): being a command, a replay has it. A seat that
+* names another's (`seat`) is refused
+*
+* @internal
+*/
+var cameraCommand = defineCommand("camera", cameraCommandFields, cameraCommanded);
+/**
+* A player's screen says a cinematic the rules played on it is over, and how (see `cinematic`'s `wait`): sent by the
+* client as the cinematic ends, so that the rules hear it in the same tick on every machine and in a replay
+*
+* @internal
+*/
+var cinematicCommand = defineCommand("cinematic", {
+	cinematic: string,
+	outcome: oneOf(...CINEMATIC_OUTCOMES)
+}, (world, player, command) => cinematicEnded(world, player, command.cinematic, command.outcome));
+/**
+* A player's screen says which answer of a cinematic's choice they picked (C3): heard by the rules in the same tick on
+* every machine and in a replay, as `cinematicChoice`
+*
+* @internal
+*/
+var cinematicChoiceCommand = defineCommand("cinematicChoice", {
+	cinematic: string,
+	question: string,
+	choice: string,
+	timedOut: optional(bool)
+}, (world, player, command) => cinematicChose(world, {
+	player,
+	cinematic: command.cinematic,
+	question: command.question,
+	choice: command.choice,
+	timedOut: !!command.timedOut
+}));
+/**
+* The commands the engine knows, which every game has
+*
+* @beta
+*/
+var coreCommands = [
+	cameraCommand,
+	orderCommand,
+	smartCommand,
+	attackCommand,
+	castCommand,
+	steerCommand,
+	autocastCommand,
+	stopCommand,
+	trainCommand,
+	researchCommand,
+	upgradeBuildingCommand,
+	cancelTrainCommand,
+	rallyCommand,
+	cancelConstructionCommand,
+	skipLineCommand,
+	pingCommand,
+	chatCommand,
+	giveCommand,
+	shareCommand,
+	surrenderCommand,
+	pauseCommand,
+	cinematicCommand,
+	cinematicChoiceCommand
+];
+/** Type and sender, the part every command has */
+var head = object({
+	type: string,
+	player: id
+});
+/**
+* Checks a command and carries it out. A command that is not what it says it is (an unknown type, a field missing
+* or of the wrong kind, a player that is not in the game) is turned away with `commandRejected`, and changes nothing
+*/
+function executeCommand(world, raw) {
+	let def;
+	let player;
+	let fields;
+	let kind = "badFields";
+	try {
+		const { type, player: sender } = head(raw, "command");
+		const found = world.registry.command(type);
+		kind = "unknownType";
+		if (!found) throw new Invalid(`there is no command "${type}"`);
+		kind = "noSuchPlayer";
+		if (!world.players.has(sender)) throw new Invalid(`there is no player ${sender}`);
+		kind = "badFields";
+		def = found;
+		player = sender;
+		fields = object(def.fields)(raw, "");
+	} catch (error) {
+		if (!(error instanceof Invalid)) throw error;
+		const { type, player, seq } = typeof raw === "object" && raw ? raw : {};
+		const sender = typeof player === "number" ? player : void 0;
+		world.events.emit(commandRejected, {
+			player: sender,
+			type: typeof type === "string" ? type : void 0,
+			kind,
+			reason: error.message
+		});
+		if (sender !== void 0 && typeof seq === "number") world.events.emit(commandHandled, {
+			player: sender,
+			seq,
+			refusal: { key: error.message }
+		});
+		return;
+	}
+	const seq = raw.seq;
+	if (world.player(player).defeated) {
+		if (typeof seq === "number") world.events.emit(commandHandled, {
+			player,
+			seq,
+			refusal: { key: "defeated" }
+		});
+		return;
+	}
+	const handling = {
+		player,
+		refusal: void 0
+	};
+	world.handling = handling;
+	try {
+		def.execute(world, player, fields);
+	} catch (error) {
+		world.caught(error, {
+			kind: "command",
+			id: def.type,
+			player
+		});
+		handling.refusal ??= { key: "failed" };
+	} finally {
+		world.handling = void 0;
+	}
+	if (typeof seq === "number") world.events.emit(commandHandled, {
+		player,
+		seq,
+		refusal: handling.refusal
+	});
+}
+/** What became of a command: to whoever sent it */
+var toldCommand = replicateEvent(commandHandled, "command", ({ player, seq, refusal }, view) => player === view.player ? {
+	type: "command",
+	seq,
+	...refusal ? { refusal } : {}
+} : void 0);
+//#endregion
+export { attackCommand, autocastCommand, cameraCommand, cancelConstructionCommand, cancelTrainCommand, castCommand, chatCommand, cinematicChoiceCommand, cinematicCommand, coreCommands, defineCommand, executeCommand, giveCommand, known, leastBusy, orderCommand, owned, pauseCommand, pingCommand, producers, rallyCommand, researchCommand, shareCommand, skipLineCommand, smartCommand, steerCommand, stopCommand, surrenderCommand, toldCommand, trainCommand, upgradeBuildingCommand };
+
+//# sourceMappingURL=commands.js.map