@v12-engine/engine 0.0.0-stage → 0.1.0

package/dist/inspect.d.ts

@@ -0,0 +1,176 @@
+import { type EntityId, type PlayerId } from './entity';
+import type { AiReport } from './ai/report';
+import type { Vec2 } from './math';
+import type { World } from './world';
+/**
+ * A part of what is inspected, as the inspector shows it
+ *
+ * @beta
+ */
+export interface InspectedSection {
+    title: string;
+    /** What it holds, plain data. Entities in it are written `footman#12`, for the inspector to link to */
+    value: unknown;
+    /** Where it is kept, for `setInspected`. Left out for what is worked out, or not to be changed by hand, like stats */
+    path?: (string | number)[];
+    /** State of the game's own (a component), rather than the engine's */
+    own?: boolean;
+}
+/**
+ * What the inspector can look at: an entity, a player, or the world itself
+ *
+ * @beta
+ */
+export type InspectTarget = {
+    entity: EntityId;
+} | {
+    player: PlayerId;
+} | {
+    world: true;
+};
+/**
+ * Something as the simulation has it, for the inspector
+ *
+ * @beta
+ */
+export interface Inspection {
+    target: InspectTarget;
+    /** What it is called: `Footman #14`, a player's name, `World` */
+    title: string;
+    /** What else says what it is: type and owner, team */
+    about: string;
+    tick: number;
+    alive: boolean;
+    /** Where it is, for an entity */
+    at?: Vec2;
+    /** What is so of it that is not a number: hidden, asleep, scenery */
+    flags: string[];
+    sections: InspectedSection[];
+    /**
+     * What the computer that plays a player is thinking, where a brain does (`Brain.report`, with the seat's timing):
+     * what the debug panel's AI tab draws. A computer player of another kind is a section (`Computer player`)
+     */
+    ai?: AiReport;
+}
+/**
+ * Something as the simulation has it right now, or null when there is no such entity or player
+ *
+ * @beta
+ */
+export declare function inspect(world: World, target: InspectTarget): Inspection | null;
+/**
+ * An entity as the list of all of them shows it
+ *
+ * @beta
+ */
+export interface EntityRow {
+    id: EntityId;
+    type: string;
+    name: string;
+    owner: PlayerId;
+    kind: string;
+    hp: number;
+    maxHp: number;
+    /** Type of what it is doing, null for nothing */
+    order: string | null;
+    scenery: boolean;
+    hidden: boolean;
+}
+/**
+ * A player as the list shows it
+ *
+ * @beta
+ */
+export interface PlayerRow {
+    id: PlayerId;
+    name: string;
+    team: number;
+    neutral: boolean;
+    defeated: boolean;
+}
+/**
+ * Everything in the world, for the list of the debug tools: what is out of sight, hidden or scenery too
+ *
+ * @beta
+ */
+export interface WorldListing {
+    tick: number;
+    players: PlayerRow[];
+    entities: EntityRow[];
+}
+/**
+ * Something that happened in the rules, as the event log keeps it
+ *
+ * @beta
+ */
+export interface LoggedEvent {
+    /** In the order they were logged, for asking for what came after */
+    seq: number;
+    /** The tick it happened in */
+    tick: number;
+    kind: 'event' | 'hook';
+    /** The engine's name for it, or a game's id */
+    name: string;
+    /** One of the game's own, rather than the engine's */
+    own: boolean;
+    /** What it said, plain data. For a hook, what the first run of it in the tick was given */
+    detail?: unknown;
+    /** The listeners that ran on an event, or the handlers of a hook */
+    ran: string[];
+    /** How many times a hook ran in the tick */
+    count?: number;
+}
+/**
+ * What a world tells whoever follows it of the rules as they run, see `World.trace`
+ *
+ * @beta
+ */
+export interface Trace {
+    /** A hook with handlers ran. `own`: a hook of the game's */
+    hook(name: string, handlers: readonly {
+        id: string;
+    }[], own: boolean, event: unknown): void;
+    /** A listener of the game is about to run, on the event going out */
+    listener(id: string): void;
+}
+/**
+ * The events and hooks of the last seconds of a world, the game's own among them, with the listeners and handlers
+ * that ran on them. Hooks run often (every target search asks one), so a hook is one line a tick, with how many times.
+ * Following costs a little: it is only on while `attach`ed
+ *
+ * @beta
+ */
+export declare class EventLog implements Trace {
+    /** Seconds of it that are kept */
+    readonly seconds: number;
+    /** Lines kept at most, however short a time they took */
+    readonly max: number;
+    private readonly list;
+    private seq;
+    /** The hooks of the tick going on, by name */
+    private hooks;
+    private hooksAt;
+    /** The event going out, which listeners that run belong to */
+    private current;
+    private world;
+    private untap;
+    constructor(
+    /** Seconds of it that are kept */
+    seconds?: number, 
+    /** Lines kept at most, however short a time they took */
+    max?: number);
+    /** Starts following a world */
+    attach(world: World): void;
+    /** Stops following it. What was logged stays */
+    detach(): void;
+    get attached(): boolean;
+    /** What was logged, oldest first. The same list, kept up to date: to read, not to keep */
+    get entries(): readonly LoggedEvent[];
+    clear(): void;
+    private event;
+    listener(id: string): void;
+    hook(name: string, handlers: readonly {
+        id: string;
+    }[], own: boolean, event: unknown): void;
+    private add;
+}

package/dist/inventory.d.ts

@@ -0,0 +1,18 @@
+import type { Entity, ItemInstance } from './entity';
+import type { InventoryInfo } from './session/protocol';
+/**
+ * The slots of what a unit carries (`UnitTypeDef.inventory`), null for an empty one: set as it is spawned (and as its
+ * type changes), for a type with slots. Sent to everyone who sees it as `InventoryInfo`: the items it carries, and to
+ * its owner and their allies the slots, for commands
+ *
+ * @beta
+ */
+export declare const inventorySlots: import("./components").Component<(ItemInstance | null)[], InventoryInfo>;
+/**
+ * The slots of what a unit carries, null for an empty one: none for a type that carries nothing (`inventorySlots`)
+ *
+ * @beta
+ */
+export declare const slotsOf: (entity: Entity) => (ItemInstance | null)[] | undefined;
+/** @beta */
+export declare const freeSlot: (entity: Entity) => number;

package/dist/items.d.ts

@@ -0,0 +1,91 @@
+import type { Entity, ItemInstance, Placed, StockState } from './entity';
+import type { StockInfo } from './session/protocol';
+import { type Vec2 } from './math';
+import type { World } from './world';
+/**
+ * An item lying on the ground
+ *
+ * @beta
+ */
+export interface GroundItem {
+    id: number;
+    item: string;
+    charges: number;
+    x: number;
+    z: number;
+}
+/** @beta */
+export declare function createItem(world: World, item: string, charges?: number): ItemInstance;
+/**
+ * Puts an item into the first free slot. False when there is none
+ *
+ * @beta
+ */
+export declare function giveItem(world: World, entity: Entity, instance: ItemInstance): boolean;
+/** @beta */
+export declare function takeItem(world: World, entity: Entity, instanceId: number): ItemInstance | undefined;
+/** @beta */
+export declare function findItem(entity: Entity, instanceId: number | undefined): ItemInstance | undefined;
+/** @beta */
+export declare function dropOnGround(world: World, instance: ItemInstance, at: Vec2): GroundItem;
+/** @beta */
+export declare function pickUp(world: World, entity: Entity, groundId: number): boolean;
+/**
+ * One use of an item that has charges. The last one takes the item with it
+ *
+ * @beta
+ */
+export declare function spendCharge(world: World, entity: Entity, instance: ItemInstance): void;
+/** Part of its price an item is bought back for */
+/**
+ * Whether someone stands close enough to a shop to trade with it. Anything with a place will do: an entity, or what a screen knows of one
+ *
+ * @beta
+ */
+export declare const atShop: (entity: Placed, shop: Placed) => boolean;
+/**
+ * What buying an item comes to for someone who carries these things: the items it is made of that are there are
+ * used up and taken off the price, and so are the parts of the ones that are not
+ *
+ * @beta
+ */
+export declare function priceOf(registry: World['registry'], item: string, carried: readonly string[]): {
+    price: number;
+    uses: string[];
+};
+/**
+ * What a shop has of each of its wares (`UnitTypeDef.sells`): how many are left and the seconds until the next one.
+ * Set as the shop is spawned, counted down by the abilities system while the shop stands; filed in the index
+ * (`world.index.with(shopStock)`); sent to everyone who sees the shop as `StockInfo` (how far the next one is, 0..1, not
+ * the seconds), the delta comparing ware by ware
+ *
+ * @beta
+ */
+export declare const shopStock: import("./components").Component<StockState[], StockInfo[]>;
+/** The player's hero that is closest to a shop and has room for the item, or for anything when none is named, if one is close enough */
+export declare function shopper(world: World, shop: Entity, player: number, item?: string): Entity | undefined;
+/**
+ * Sells an item to a hero standing at the shop: the one that is named, or the closest one with room.
+ * Tells the player why when it cannot
+ *
+ * @beta
+ */
+export declare function buy(world: World, shop: Entity, item: string, player: number, buyer?: Entity): boolean;
+/**
+ * Whether a shop the player can trade with is close enough to the entity
+ *
+ * @beta
+ */
+export declare function shopNear(world: World, entity: Entity): Entity | undefined;
+/**
+ * Gives an item back at a shop nearby, for a part of its price. What has charges is worth as much as is left of it
+ *
+ * @beta
+ */
+export declare function sell(world: World, entity: Entity, instanceId: number): boolean;
+/** What a dead unit leaves behind: by its table of chances, or as its code decides */
+export declare function dropLoot(world: World, entity: Entity, killer?: Entity): void;
+/** An item picked up, to those who see who picked it */
+export declare const toldPicked: import("./replication").ReplicatedEvent;
+/** The items on the ground where the player sees (`Snapshot.items`) */
+export declare const itemsPart: import("./replication").SnapshotPart<keyof import(".").Snapshot>;

package/dist/lanes.d.ts

@@ -0,0 +1,213 @@
+import type { GamePack } from './packs/pack';
+import type { Entity } from './entity';
+import type { GameMap, MapPath } from './map';
+import { type MapFieldDef, type MapProblem, type MapThing } from './mapFields';
+import type { Vec2 } from './math';
+import type { PlayerId } from './entity';
+import type { System } from './registry';
+import type { World } from './world';
+/**
+ * The kind of thing a spawner is: where it is kept in the map's data, by this id
+ *
+ * @beta
+ */
+export declare const LANE_SPAWNERS = "lanes.spawners";
+/**
+ * A spawner as the editor offers it (a `MapKindDef` of `@v12-engine/client`): its tool, its fields, a ring at each, in
+ * the scene's `kinds`
+ *
+ * @beta
+ */
+export declare const LANE_SPAWNER_KIND: {
+    id: string;
+    name: string;
+    plural: string;
+    hint: string;
+    icon: string;
+    color: [number, number, number];
+    fields: Omit<MapFieldDef, "for">[];
+    reach: number;
+};
+/**
+ * A lane, as the rules read it: the path, and its two ends, each with the spawner of the side whose waves start there
+ *
+ * @beta
+ */
+export interface Lane {
+    /** The name of its path (`world.map.path(name)`), what orders that follow it are given */
+    path: string;
+    points: readonly Vec2[];
+    /** Its spawners, by the end of the lane they are at: the first point's, then the last's. Either is missing on a map not finished */
+    ends: [LaneEnd | undefined, LaneEnd | undefined];
+}
+/**
+ * One end of a lane: the spawner there, and whose
+ *
+ * @beta
+ */
+export interface LaneEnd {
+    spawner: MapThing;
+    player: PlayerId;
+    at: Vec2;
+}
+/**
+ * The lanes of a map: every path a spawner is on, with what stands at each end
+ *
+ * @beta
+ */
+export declare function mapLanes(map: {
+    paths: readonly MapPath[];
+    data: Record<string, unknown>;
+}): Lane[];
+/**
+ * The lanes of a world's map (`mapLanes`): what waves walk
+ *
+ * @beta
+ */
+export declare const lanesOf: (world: World) => Lane[];
+/**
+ * What is wrong with the lanes of a map, for the editor's checks (`MapEditorDef.check`): a spawner on no lane or away
+ * from its ends, a lane without a spawner at each end, or with the same side at both
+ *
+ * @beta
+ */
+export declare function checkLanes(map: GameMap): MapProblem[];
+/**
+ * A wave about to come out of a spawner: which of that spawner's it is (1 and up), the lane and the end it walks from,
+ * and whose. What `LanesOptions.wave` makes the units of
+ *
+ * @beta
+ */
+export interface LaneWave {
+    number: number;
+    lane: Lane;
+    from: 0 | 1;
+    player: PlayerId;
+}
+/**
+ * What a game's lanes do (`withLanes`). Every part has the engine's own when left out
+ *
+ * @beta
+ */
+export interface LanesOptions {
+    /**
+     * The unit types of the engine's waves, by role: three to five close, two or three that shoot, a siege now and then
+     * (`melee` and `ranged` are needed, `siege` is left out of the waves when it is). The engine names none: a game that
+     * gives no `wave` of its own says these
+     */
+    minions?: {
+        melee: string;
+        ranged: string;
+        siege?: string;
+    };
+    /** The unit types of a wave, in the order they come out: the engine's grow with time, from `minions` */
+    wave?: (world: World, wave: LaneWave) => string[];
+    /** Seconds from the start to the first wave, and between waves: 20 and 30 when left out */
+    firstWave?: number;
+    every?: number;
+    /**
+     * Where a minion goes once it is at the far end of its lane, fighting on the way: the nearest structure of another
+     * team to that end when left out (their core), the end itself when there is none
+     */
+    goal?: (world: World, minion: Entity, lane: Lane, from: 0 | 1) => Vec2 | undefined;
+    /**
+     * What the lane towers are: they hit minions before anything else, and a hero who hits a hero of their side within
+     * their reach before minions (as in a MOBA). Structures that attack, other than cores, when left out
+     */
+    towers?: (world: World, entity: Entity) => boolean;
+    /**
+     * What the cores are: the unit type's id, or a test of a unit. A side whose cores have all fallen has lost, and the
+     * last side with one wins. Said by the game (the engine names none); `false` keeps the game's own way of winning
+     * (`GameModule.victory`)
+     */
+    cores: string | ((world: World, entity: Entity) => boolean) | false;
+    /** Seconds a hero who hit a hero is the towers' first target for: 3 when left out */
+    towerAggro?: number;
+    /**
+     * Minions turn on a hero who hits a hero of their side near them (within `radius` cells of it), chase it for `chase`
+     * seconds at most and no further than `leash` cells from their lane, then go back to it the way they were going:
+     * 7, 2.5 and 10 when left out. `false` for minions that keep to their lane
+     */
+    minionAggro?: {
+        radius?: number;
+        chase?: number;
+        leash?: number;
+    } | false;
+}
+/**
+ * A minion of a lane: the lane it walks (its path's name), from which end. On every unit a wave brings
+ *
+ * @beta
+ */
+export declare const laneMinion: import("./components").Component<{
+    lane: string;
+    from: 0 | 1;
+    chase?: {
+        target: number;
+        until: number;
+    };
+}, {
+    lane: string;
+    from: 0 | 1;
+    chase?: {
+        target: number;
+        until: number;
+    };
+}>;
+/** How many waves each spawner has sent, by its id, and whether the waves were set going */
+export declare const lanesState: import("./components").Component<{
+    started: boolean;
+    waves: Record<string, number>;
+    chasing?: number[];
+}, {
+    started: boolean;
+    waves: Record<string, number>;
+    chasing?: number[];
+}>;
+/**
+ * The engine's waves: three close and two that shoot, one more close every fourth wave and one more that shoots every
+ * sixth, a siege every third wave (two from the twelfth). Of the types a game has
+ *
+ * @beta
+ */
+export declare function defaultWave(world: World, wave: LaneWave, minions: NonNullable<LanesOptions['minions']>): string[];
+/**
+ * Sends a spawner's next wave now, whatever its timer, as the game's lanes say (`LanesOptions`): for scripts, tests and debug tools. Its units come out by the
+ * spawner, walk the lane fighting what they meet (`attackPath`), then go for the goal at its far end. Gives back the
+ * units, none for a spawner on no lane
+ *
+ * @beta
+ */
+export declare function sendWave(world: World, spawner: number, options: Partial<LanesOptions>): Entity[];
+/**
+ * How many waves a spawner has sent
+ *
+ * @beta
+ */
+export declare const wavesSent: (world: World, spawner: number) => number;
+/**
+ * A game with lanes: its maps' lanes checked in the editor, and waves of minions sent along them from every spawner,
+ * the first `firstWave` seconds in and one every `every` seconds after, each from the `wave` of its number (see
+ * `LanesOptions`). What it adds goes with what the game has: its timers and components saved, its check after its own
+ *
+ * @beta
+ */
+export declare function withLanes(options: LanesOptions): GamePack;
+/**
+ * When a hero last hit a hero of another side, in seconds of the game's time: what the lane towers of the side it hit
+ * go for first, for a while (`LanesOptions.towerAggro`)
+ *
+ * @beta
+ */
+export declare const heroStrike: import("./components").Component<{
+    at: number;
+}, {
+    at: number;
+}>;
+/**
+ * The rule of a lanes game: a side whose cores have all fallen is out, and the last side with a core wins. A side
+ * takes part once it has had a core
+ *
+ * @beta
+ */
+export declare function coreVictory(cores: (world: World, entity: Entity) => boolean): System;

package/dist/life.d.ts

@@ -0,0 +1,53 @@
+import { type Entity } from './entity';
+import type { DamageOptions, DeathReason, World } from './world';
+/**
+ * How a world's entities are hurt, healed and die
+ *
+ * @beta
+ */
+export declare class Life {
+    private readonly world;
+    /** Who died and is to be taken out of the world at the end of the tick (`World.step`) */
+    readonly dead: Entity[];
+    constructor(world: World);
+    /**
+     * Deals damage. In order:
+     * 1. the `beforeDamage` hook, which can change the amount or call it off;
+     * 2. armor or magic resist, then shields, take their part;
+     * 3. the rest comes off the target's health, and it dies when nothing is left (see `kill`);
+     * 4. the `afterDamage` hook, for what follows from a hit: life steal, effects on hit.
+     */
+    damage(target: Entity, amount: number, source?: Entity, options?: DamageOptions): void;
+    /** Gives health back, after the `beforeHeal` hook had its say. Returns how much of it was needed */
+    heal(target: Entity, amount: number, source?: Entity): number;
+    /**
+     * Kills an entity by the rules, not by damage: felled, cancelled, run out of time. `attack` says that an attack of
+     * the killer did it; `reason` why (`DeathReason`: `killed` when left out, or the game's own word, `sold`), for the
+     * hooks and the screen
+     */
+    kill(entity: Entity, killer?: Entity, attack?: boolean, reason?: DeathReason): void;
+    /**
+     * How anything dies. In order:
+     * 1. the `beforeDeath` hook, which can keep it alive;
+     * 2. its orders and production are called off;
+     * 3. the `death` hook, while it still stands where it was: experience, loot, bounty;
+     * 4. it leaves the world (a fallen hero waits out of it to be brought back);
+     * 5. the `afterDeath` hook, for what follows: effects of the killer on a kill.
+     */
+    private die;
+    /** Who is being killed right now: their `death` hooks are running. They take no damage, no healing, and die once */
+    private readonly dying;
+    /** Whether an entity is being killed right now: alive still, while its `death` hooks run, and past saving */
+    isDying(entity: Entity): boolean;
+    /** What follows the `death` hooks: the entity is gone from the world, and it is told */
+    private fall;
+    private detach;
+}
+/** A death, to those who see the dead: who killed it where they see the killer too (`SessionEvent` `death`) */
+export declare const toldDeath: import("./replication").ReplicatedEvent;
+/** A hit, to those who see who took it: who dealt it where they see them too */
+export declare const toldDamage: import("./replication").ReplicatedEvent;
+/** Healing, to those who see who was healed */
+export declare const toldHeal: import("./replication").ReplicatedEvent;
+/** A critical strike's number over who took it */
+export declare const toldCrit: import("./replication").ReplicatedEvent;