@v12-engine/engine 0.0.0-stage → 0.1.1

package/dist/objectives.d.ts

@@ -0,0 +1,93 @@
+import type { PlayerId } from './entity';
+import { type Message, type MessageRef } from './messages';
+import type { System } from './registry';
+import type { World } from './world';
+/**
+ * What a player is set to do, in a mission: survive ten waves, keep the hero alive, build a frost tower
+ *
+ * @beta
+ */
+export interface ObjectiveDef {
+    /** Shared by every game, like other ids: give it a prefix of the game's (`'td.hold'`) */
+    id: string;
+    /** What it says, in the words of the game: a message key, with params where it shows numbers */
+    text: MessageRef;
+    /** Whether the mission needs it: all of them done is a victory, one failed a defeat. True when left out */
+    required?: boolean;
+    /** More about it, in the words of the game: shown under it when the player opens it in the quest panel (campaign plan CP5) */
+    detail?: MessageRef;
+}
+/**
+ * Typed help for writing one
+ *
+ * @beta
+ */
+export declare const defineObjective: (def: ObjectiveDef) => ObjectiveDef;
+/** @beta */
+export type ObjectiveStatus = 'open' | 'done' | 'failed';
+/**
+ * An objective of a player, as it stands. Plain data: it is kept in the player's state, and sent to their screen
+ *
+ * @beta
+ */
+export interface ObjectiveState {
+    id: string;
+    text: Message;
+    required: boolean;
+    status: ObjectiveStatus;
+    /** How far along it is, for the ones that count: 3 of 10 waves */
+    progress?: {
+        value: number;
+        max: number;
+    };
+    /** Why it failed, for a failed one that says */
+    reason?: Message;
+    /** More about it (`ObjectiveDef.detail`) */
+    detail?: Message;
+}
+/** A player's objectives, in the order they were given */
+export declare const objectives: import("./components").Component<ObjectiveState[], ObjectiveState[]>;
+/**
+ * The objectives of the players of a world. What changes in them is the engine's `objectiveChanged` event, which
+ * the player is shown, and which a game's listeners and sequences can wait for
+ *
+ * @beta
+ */
+export declare class Objectives {
+    private readonly world;
+    constructor(world: World);
+    /** Gives a player an objective, open. Its words' params and its progress can be given with it */
+    add(player: PlayerId, def: ObjectiveDef, options?: {
+        params?: Message['params'];
+        progress?: {
+            value: number;
+            max: number;
+        };
+    }): ObjectiveState;
+    /** Done. Only an open one can be */
+    complete(player: PlayerId, id: string): void;
+    /** Failed, and why when that is worth saying. Only an open one can be */
+    fail(player: PlayerId, id: string, reason?: MessageRef): void;
+    /** How far along an open one is. Its words' params can change with it: "wave 3 of 10" */
+    progress(player: PlayerId, id: string, value: number, options?: {
+        max?: number;
+        params?: Message['params'];
+    }): void;
+    /** A player's objectives, in the order they were given */
+    of(player: PlayerId): readonly ObjectiveState[];
+    get(player: PlayerId, id: string): ObjectiveState;
+    /** Whether a player has the objective, open or not */
+    has(player: PlayerId, id: string): boolean;
+    private settle;
+    private changed;
+}
+/**
+ * The rule of a mission: a player who failed an objective the mission needs is out, and a player who did all of
+ * them wins, for their team. Like a melee game, a team whose players are all out loses, and the last team standing
+ * wins. A game uses it as its `victory`
+ *
+ * @beta
+ */
+export declare const objectiveVictory: System;
+/** An objective changed, to whose it is */
+export declare const toldObjective: import("./replication").ReplicatedEvent;

package/dist/orders/basic.d.ts

@@ -0,0 +1,96 @@
+import { type EntityId } from '#engine/entity';
+import type { Vec2 } from '#engine/math';
+import type { OrderBehavior, OrderInits } from '#engine/registry';
+/**
+ * What `hold` keeps in its order: what it is fighting, 0 for nothing
+ *
+ * @beta
+ */
+export interface HoldState {
+    /** What it fights, 0 for nothing */
+    target?: EntityId;
+}
+/**
+ * What `attack` keeps: whether it lost sight and walks to where it last saw its target
+ *
+ * @beta
+ */
+export interface AttackState {
+    /** Walking to where it last saw its target */
+    searching?: boolean;
+    /** Where it last saw it */
+    lastSeen?: Vec2;
+}
+/**
+ * What walking to a point and fighting on the way keeps (`attackMove`, `attackPath`, `patrol`)
+ *
+ * @beta
+ */
+export interface AdvanceState {
+    /** What it fights, 0 for nothing */
+    target?: EntityId;
+    /** To walk on again once the fight is over */
+    resume?: boolean;
+    /** Held up behind its own, waiting */
+    waiting?: boolean;
+    /** The point it last set out for */
+    heading?: Vec2;
+}
+/**
+ * What an order along a path keeps (`followPath`, `attackPath`): the bend it goes to next, and which way. Set as it starts
+ *
+ * @beta
+ */
+export interface AlongPath {
+    /** The bend of the path it goes to next, by its place in the path */
+    leg: number;
+    /** Which way along the path: towards its last point (1) or its first (-1) */
+    step: 1 | -1;
+}
+/**
+ * What `patrol` keeps: its two ends and the one it goes to (set as it starts), and whether it found one out of reach
+ *
+ * @beta
+ */
+export interface PatrolState extends AdvanceState {
+    /** The point it was sent to, and where it stood */
+    ends: [Vec2, Vec2];
+    /** Which of the two it goes to */
+    leg: number;
+    /** It could not get to the other end */
+    stuck?: boolean;
+}
+/**
+ * What `follow` keeps: the tick it last set out after its target
+ *
+ * @beta
+ */
+export interface FollowState {
+    /** The tick it last set out after its target */
+    tried?: number;
+}
+/**
+ * What `attackGround` keeps: whether it walked into range already
+ *
+ * @beta
+ */
+export interface AttackGroundState {
+    /** It walked into range already */
+    walked?: boolean;
+}
+/** What a move remembers: what it shoots at on its way, with an attack that fires on the move (`AttackDef.onTheMove`) */
+export interface MoveState {
+    shooting?: number;
+}
+export declare const moveOrder: OrderBehavior<MoveState, OrderInits['move']>;
+/** Stand still and only fight what comes into range */
+export declare const holdOrder: OrderBehavior<HoldState, OrderInits['hold']>;
+export declare const attackOrder: OrderBehavior<AttackState, OrderInits['attack']>;
+/** Walk to a point, fighting everything met on the way */
+export declare const attackMoveOrder: OrderBehavior<AdvanceState, OrderInits['attackMove']>;
+/** Walk back and forth between where the unit stands and a point, fighting everything met on the way, until told otherwise */
+export declare const patrolOrder: OrderBehavior<PatrolState, OrderInits['patrol']>;
+/** Stay with a unit wherever it goes, for as long as it lives */
+export declare const followOrder: OrderBehavior<FollowState, OrderInits['follow']>;
+/** Attack a spot on the ground, or what stands there, until told otherwise. For attacks that hit an area */
+export declare const attackGroundOrder: OrderBehavior<AttackGroundState, OrderInits['attackGround']>;

package/dist/orders/build.d.ts

@@ -0,0 +1,91 @@
+import { type Cost, type UnitTypeDef } from '#engine/defs';
+import { type Entity, type EntityId, type PlayerId } from '#engine/entity';
+import { type Rect, type Vec2 } from '#engine/math';
+import type { OrderBehavior, OrderInits } from '#engine/registry';
+import type { World } from '#engine/world';
+import { type MessageRef } from '#engine/messages';
+/**
+ * Ground a structure of this type covers when placed at `point`
+ *
+ * @beta
+ */
+export declare function siteOf(def: UnitTypeDef, point: Vec2): Rect & {
+    cellX: number;
+    cellZ: number;
+};
+/**
+ * Why this structure cannot be placed here right now, or undefined when it can. The ground has to be free,
+ * then the `canPlace` hook has its say. With `fog`, ground the player has never seen counts as taken too:
+ * that is for the player's own preview, which must not give away what is in the dark
+ *
+ * @beta
+ */
+export declare function placementProblem(world: World, def: UnitTypeDef, point: Vec2, player?: PlayerId, fog?: boolean): MessageRef | undefined;
+/**
+ * The resource a building that goes up on one (`UnitTypeDef.builtOn`) would stand on when placed at `point`: one of its
+ * kind that covers the very same ground. None where there is none
+ *
+ * @beta
+ */
+export declare function resourceAt(world: World, def: UnitTypeDef, point: Vec2): Entity | undefined;
+/**
+ * Which cells of the ground a structure would cover at `point` are in the way, row by row from its corner (`w` across,
+ * `d` rows: `siteOf`'s cell first): taken (`free` says no), or not explored (`explored` says no, where it is asked).
+ * What a preview draws cell by cell (RV88); `placementProblem` says the whole, the game's own say among it. None for a
+ * structure built on a resource, whose ground is the resource's
+ *
+ * @beta
+ */
+export declare function placementCells(def: UnitTypeDef, point: Vec2, free: (cellX: number, cellZ: number) => boolean, explored?: (cellX: number, cellZ: number) => boolean): boolean[] | undefined;
+/**
+ * Whether this structure can be placed here right now, see `placementProblem`
+ *
+ * @beta
+ */
+export declare function canPlaceStructure(world: World, def: UnitTypeDef, point: Vec2, player?: PlayerId, fog?: boolean): boolean;
+/**
+ * What `construct` keeps: the seconds to its builder's next blow of the hammer
+ *
+ * @beta
+ */
+export interface WorkState {
+    /** Seconds to its next blow, for the screen (`worked`) */
+    hammer?: number;
+}
+/**
+ * What `build` keeps: whether it walked to the site already, and the building once it is put down
+ *
+ * @beta
+ */
+export interface BuildState extends WorkState {
+    /** It walked to the site already */
+    walked?: boolean;
+    /** It walks through the others: its walk to the site failed once, held up among them (workers round a mine) */
+    ghost?: boolean;
+    /** The building, once it is put down */
+    building?: EntityId;
+}
+/**
+ * What `repair` keeps: whether it walked to it already, what of the cost it still owes, the seconds to its next swing
+ *
+ * @beta
+ */
+export interface RepairState {
+    /** It walked to it already */
+    walked?: boolean;
+    /** What of the cost of the repair it owes still */
+    owed?: Cost;
+    /** Seconds to its next swing */
+    hammer?: number;
+}
+export declare const buildOrder: OrderBehavior<BuildState, OrderInits['build']>;
+/** Work on an existing construction site: resuming an abandoned one or helping another builder */
+export declare const constructOrder: OrderBehavior<WorkState, OrderInits['construct']>;
+/**
+ * Whether a worker of the player could mend it
+ *
+ * @beta
+ */
+export declare function canRepair(world: World, player: number, target: Entity): boolean;
+/** Mend a damaged building. It is paid for as the work goes on */
+export declare const repairOrder: OrderBehavior<RepairState, OrderInits['repair']>;

package/dist/orders/cast.d.ts

@@ -0,0 +1,105 @@
+import { type AbilityDef } from '#engine/defs';
+import { type Entity, type ItemInstance } from '#engine/entity';
+import { type Vec2 } from '#engine/math';
+import type { OrderBehavior, OrderInits } from '#engine/registry';
+import type { World } from '#engine/world';
+import { type Message } from '#engine/messages';
+import { type TargetFacts } from '#engine/shared';
+/**
+ * Whether an ability may be used on a target: as its `targets` say, and the `canTarget` hook
+ *
+ * @beta
+ */
+export declare function validTarget(world: World, caster: Entity, ability: AbilityDef, target: Entity): boolean;
+/**
+ * What a target is to a caster, for `targetRefusal`
+ *
+ * @beta
+ */
+export declare function targetFacts(world: World, caster: Entity, target: Entity, ability?: AbilityDef): TargetFacts;
+/**
+ * How far away the target of an ability may be: what it says, and for some as far as the caster's attacks reach on top
+ *
+ * @beta
+ */
+export declare function castRange(world: World, caster: Entity, ability: AbilityDef, level: number): number;
+/**
+ * Seconds of the wind-up of an ability: in code, or as it says
+ *
+ * @beta
+ */
+export declare const castTimeOf: (world: World, caster: Entity, ability: AbilityDef, level: number) => number;
+/**
+ * Whether the ability is one of the spells the hero brought along, as opposed to what it learned
+ *
+ * @beta
+ */
+export declare const isSpell: (entity: Entity, ability: AbilityDef) => boolean;
+/**
+ * Why an ability cannot be used right now, or undefined when it can. Items ask for no mana, and silence does not stop them
+ *
+ * @beta
+ */
+export declare function notReady(world: World, entity: Entity, ability: AbilityDef, item?: ItemInstance): Message | undefined;
+/**
+ * Pays for an ability and lets it happen. In order:
+ * 1. the `beforeCast` hook, which can change the mana cost and the cooldown, or call it off;
+ * 2. the caster pays, the cooldown starts, and one of its charges is spent where it has them;
+ * 3. the effects of the ability happen;
+ * 4. the `afterCast` hook, for what follows: the caster's passives that react to its casts.
+ */
+export declare function fire(world: World, caster: Entity, ability: AbilityDef, target: Entity | undefined, item?: ItemInstance): void;
+/**
+ * Casts what goes off on the spot without the caster dropping what it is doing: a hero drinks a potion while it walks,
+ * and leaps in the middle of a run. `point` is where it is aimed, for what goes off towards somewhere.
+ * False when it cannot be cast this way, and takes an order
+ */
+export declare function castAside(world: World, caster: Entity, from: {
+    ability?: string;
+    item?: number;
+}, point?: Vec2): boolean;
+/**
+ * What `cast` keeps in its order: the seconds of its wind-up left (from when it is in range), whether it walked to its
+ * point already, whether it is past turning back (`isCommitted`), what it channels, and whether the ability carries the
+ * caster off (a dash)
+ *
+ * @beta
+ */
+export interface CastState {
+    /** Seconds of its wind-up left, from when it is in range */
+    windup?: number;
+    /** It walked to its point already */
+    walked?: boolean;
+    /** Past turning back (`isCommitted`) */
+    locked?: boolean;
+    /** What it channels, once it fired */
+    channel?: CastChannel;
+    /** The ability carries the caster off (a dash): the order is over when it lands */
+    rushing?: boolean;
+}
+/** Use an ability: walk into range, turn towards the target, wind up, fire */
+export declare const castOrder: OrderBehavior<CastState, OrderInits['cast']>;
+/** A channelled ability being kept up: plain data, in the order's state, so that a save has it */
+/**
+ * An ability being channelled, kept in the cast order (`CastState.channel`)
+ *
+ * @beta
+ */
+export interface CastChannel {
+    /** The ability, and its level */
+    ability: string;
+    level: number;
+    /** What it is aimed at, and where */
+    target?: number;
+    point: Vec2;
+    /** Seconds still to go, and gone */
+    left: number;
+    elapsed: number;
+    /** Over: kept up to its end, or broken off */
+    done?: boolean;
+}
+/**
+ * A caster was hurt: a channelled ability it keeps up that breaks on damage (`channel.breaksOnDamage`, a recall) is
+ * broken off, as another order would
+ */
+export declare function hurtWhileChannelling(world: World, caster: Entity): void;

package/dist/orders/facts.d.ts

@@ -0,0 +1,14 @@
+/**
+ * What the engine asks of an entity's current order (`orderSays`): its behaviour's to say (`OrderBehavior.committed`,
+ * `waiting`, `channelling`, `building`), where it once read those fields of any order's state by name
+ */
+import type { Entity } from '#engine/entity';
+import type { OrderFact } from '#engine/registry';
+import type { World } from '#engine/world';
+/**
+ * What an entity's current order says of a fact (`OrderFact`): false for an entity with no order, or an order whose
+ * behaviour says nothing of it
+ *
+ * @beta
+ */
+export declare function orderSays(world: World, entity: Entity, fact: OrderFact): boolean;

package/dist/orders/harvest.d.ts

@@ -0,0 +1,94 @@
+import type { ResourceKind } from '#engine/defs';
+import { type Entity, type EntityId, type HarvesterState } from '#engine/entity';
+import type { GatheringInfo } from '#engine/session/protocol';
+import { type Vec2 } from '#engine/math';
+import type { OrderBehavior, OrderInits } from '#engine/registry';
+import type { World } from '#engine/world';
+/**
+ * What a worker carries and where it gathers (`UnitTypeDef.harvester`): set as it is spawned (and as its type changes),
+ * for a type that gathers. Its owner and their allies are told what it carries (`GatheringInfo`)
+ *
+ * @beta
+ */
+export declare const gathering: import("#engine/components").Component<HarvesterState, GatheringInfo>;
+/**
+ * What a worker carries and where it gathers: none for a type that does not gather (`gathering`)
+ *
+ * @beta
+ */
+export declare const harvesterOf: (entity: Entity) => HarvesterState | undefined;
+/** Closest building of the player that takes the resource */
+export declare function findDropOff(world: World, entity: Entity, kind?: ResourceKind | null | undefined): Entity | undefined;
+/**
+ * Whether a worker may gather from a resource: one of a kind it gathers (`harvester.kinds`), and then as the game's
+ * `canHarvest` hook says
+ *
+ * @beta
+ */
+export declare function canHarvest(world: World, worker: Entity, source: Entity): boolean;
+/**
+ * Closest resource with something left within `radius` of the point, of a kind when one is named.
+ * `free` only takes what another worker can still get at. Among equally close ones, the oldest.
+ */
+export declare function findResource(world: World, near: Vec2, radius: number, kind?: ResourceKind, free?: boolean, worker?: Entity, skip?: readonly EntityId[]): Entity | undefined;
+/**
+ * What harvesting keeps through every step of it, and from one load to the next: the kind it gathers and where it last
+ * did, the resource it holds a place at (`claimed`, a tree, a place round a building on a resource), the building it
+ * gathers at (`inPlace`), the place it walks to and the one it waits at, whether it walked to its place already, the
+ * seconds to its next swing (`chop`: the rhythm goes on from one load to the next), the hall it brings its loads to
+ *
+ * @beta
+ */
+export interface HarvestKept {
+    kind?: ResourceKind;
+    at?: Vec2;
+    claimed?: EntityId;
+    inPlace?: EntityId;
+    spot?: Vec2;
+    waitSpot?: Vec2;
+    walked?: boolean;
+    /** The trees it walked to and could not get next to, the last few: not gone for again by this order */
+    outOfReach?: EntityId[];
+    chop?: number;
+    dropOff?: EntityId;
+}
+/**
+ * Walking to its resource, and to its place at it (`HarvestState`)
+ *
+ * @beta
+ */
+export interface HarvestToResource extends HarvestKept {
+    phase: 'toResource';
+}
+/**
+ * At work (`HarvestState`): the seconds of it left, and what it works (`working`) or is inside of (a mine's, `inside`)
+ *
+ * @beta
+ */
+export interface HarvestGathering extends HarvestKept {
+    phase: 'gathering';
+    timer: number;
+    working?: EntityId;
+    inside?: EntityId;
+}
+/**
+ * Bringing the load home (`HarvestState`): whether it is its last, the resource used up
+ *
+ * @beta
+ */
+export interface HarvestToDropOff extends HarvestKept {
+    phase: 'toDropOff';
+    last?: boolean;
+}
+/**
+ * What `harvest` and `return` keep in their orders: the step it is at, with what that step keeps beside what every
+ * step does (`HarvestKept`). A step's own fields stay in the order as it goes on to the next (a save has them as they
+ * were), and are read only in their step
+ *
+ * @beta
+ */
+export type HarvestState = HarvestToResource | HarvestGathering | HarvestToDropOff;
+/** Gather from a resource, bring it home, repeat */
+export declare const harvestOrder: OrderBehavior<HarvestState, OrderInits['harvest']>;
+/** Hand in what the worker carries, then go back to gathering */
+export declare const returnOrder: OrderBehavior<HarvestState, OrderInits['return']>;

package/dist/orders/idle.d.ts

@@ -0,0 +1,7 @@
+import type { Entity } from '#engine/entity';
+import type { World } from '#engine/world';
+/**
+ * What units do without orders: attack enemies that come close, fight back
+ * when attacked, and return to where they stood afterwards.
+ */
+export declare function idle(world: World, entity: Entity, dt: number): void;

package/dist/orders/items.d.ts

@@ -0,0 +1,14 @@
+import type { OrderBehavior, OrderInits } from '#engine/registry';
+/**
+ * What the item orders keep: whether they walked to it already
+ *
+ * @beta
+ */
+export interface ItemOrderState {
+    /** It walked to it already */
+    walked?: boolean;
+}
+/** Walk to an item on the ground and take it */
+export declare const pickUpOrder: OrderBehavior<ItemOrderState, OrderInits['pickUp']>;
+/** Put an item down somewhere, or hand it to someone */
+export declare const dropItemOrder: OrderBehavior<ItemOrderState, OrderInits['dropItem']>;

package/dist/orders/queue.d.ts

@@ -0,0 +1,24 @@
+import type { Entity, Order } from '#engine/entity';
+import type { OrderInit } from '#engine/registry';
+import type { World } from '#engine/world';
+/** Classic RTS games cap queues as well. Mostly a guard against runaway shift-clicking */
+export declare const MAX_QUEUED_ORDERS = 32;
+export declare function createOrder(world: World, init: OrderInit, groupId?: number): Order;
+/** Back to a neutral stance between orders: not walking, not mid swing, free to be pushed. */
+export declare function resetStance(world: World, entity: Entity): void;
+/** Drops everything the entity was doing */
+export declare function clearOrders(world: World, entity: Entity): void;
+/** Whether the entity is in the middle of something it cannot be called away from, like casting (`OrderBehavior.committed`) */
+export declare const isCommitted: (world: World, entity: Entity) => boolean;
+/**
+ * Drops what the entity was doing, as far as it lets itself be called away:
+ * what it is committed to is finished first, only what was to come after is dropped.
+ */
+export declare function interrupt(world: World, entity: Entity): void;
+/**
+ * Gives an order. Queued orders wait their turn, anything else replaces what the unit is doing,
+ * or comes right after it when the unit is committed to it.
+ */
+export declare function giveOrder(world: World, entity: Entity, order: Order, queue?: boolean): void;
+/** Removes the order at the front of the queue once it finished */
+export declare function completeOrder(world: World, entity: Entity, order: Order): void;