@v12-engine/engine 0.0.0-stage → 0.1.1

package/dist/packs/director/index.d.ts

@@ -0,0 +1,81 @@
+import type { GamePack } from '#engine/packs/pack';
+/** @beta */
+export declare const DIRECTOR = "director";
+/**
+ * The cinematic playing on each player's screen, by its id, as their screen said (`cinematicPlaying`): whose
+ * director's commands are taken
+ *
+ * @beta
+ */
+export declare const directing: import("#engine/components").Component<Record<number, string>, Record<number, string>>;
+/**
+ * The units a cinematic made invulnerable (`director` with `invulnerable`): nothing hurts or kills them until it says
+ * otherwise
+ *
+ * @beta
+ */
+export declare const directorInvulnerable: import("#engine/components").Component<true, true>;
+/**
+ * What a director's command does (`DirectorCommand.action`)
+ *
+ * @beta
+ */
+export declare const DIRECTOR_ACTIONS: readonly ['spawn', 'remove', 'kill', 'teleport', 'scale', 'invulnerable', 'owner', 'order', 'facing'];
+/** @beta */
+export type DirectorAction = (typeof DIRECTOR_ACTIONS)[number];
+/**
+ * The orders a director's command gives (`order`): to a spot, or at a unit
+ *
+ * @beta
+ */
+export declare const DIRECTOR_ORDERS: readonly ['move', 'attack', 'attackMove', 'patrol', 'stop', 'hold'];
+/**
+ * A player's screen says a cinematic began on it (`playing: true`, its id) or ended: while one plays there, the
+ * director's commands it sends are taken
+ *
+ * @beta
+ */
+export declare const cinematicPlayingCommand: import("#engine/commands").DefinedCommand<"cinematicPlaying", {
+    cinematic: import("#engine/fields").Check<string>;
+    playing: import("#engine/fields").Check<boolean>;
+}>;
+/**
+ * What a game's director takes (`withDirector(options)`)
+ *
+ * @beta
+ */
+export interface DirectorOptions {
+    /**
+     * The cinematics it plays in, by id: a screen that says another began is turned away (and counted), so that on a
+     * server a player's own client cannot direct a game with a cinematic made up. Any when left out
+     */
+    cinematics?: readonly string[];
+}
+/**
+ * A cinematic's say over the game (see the top of this file): `action` with what it takes. `unit` is the one it is
+ * done to (any player's); `spawn` puts one of `unitType` down for `owner` at `at`, turned to `facing`, named `name` for
+ * what comes after it in the cinematic (`world.named`)
+ *
+ * @beta
+ */
+export declare const directorCommand: import("#engine/commands").DefinedCommand<"director", {
+    cinematic: import("#engine/fields").Check<string>;
+    action: import("#engine/fields").Check<"facing" | "invulnerable" | "kill" | "order" | "owner" | "remove" | "scale" | "spawn" | "teleport">;
+    unit: import("#engine/fields").Check<number | undefined>;
+    unitType: import("#engine/fields").Check<string | undefined>;
+    owner: import("#engine/fields").Check<number | undefined>;
+    at: import("#engine/fields").Check<import("../..").Vec2 | undefined>;
+    facing: import("#engine/fields").Check<number | undefined>;
+    scale: import("#engine/fields").Check<number | undefined>;
+    on: import("#engine/fields").Check<boolean | undefined>;
+    name: import("#engine/fields").Check<string | undefined>;
+    order: import("#engine/fields").Check<"attack" | "attackMove" | "hold" | "move" | "patrol" | "stop" | undefined>;
+    target: import("#engine/fields").Check<number | undefined>;
+}>;
+/**
+ * The director's pack (see the top of this file): its commands, what it keeps, and what keeps a unit it made
+ * invulnerable so. `packs: [withDirector()]`, or `withDirector({ cinematics: ['intro'] })` for those alone
+ *
+ * @beta
+ */
+export declare function withDirector(options?: DirectorOptions): GamePack;

package/dist/packs/heroes/campaign.d.ts

@@ -0,0 +1,137 @@
+import { type HeroItem, type HeroRecord } from './carry';
+import type { Entity, PlayerId } from '#engine/entity';
+import type { Vec2 } from '#engine/math';
+import type { Purse } from '#engine/player';
+import { type VeterancyState } from '#engine/veterancy';
+import type { World } from '#engine/world';
+/**
+ * How a mission of a campaign went, the last time it was won
+ *
+ * @beta
+ */
+export interface MissionResult {
+    /** How long it took, in seconds of the game */
+    seconds: number;
+    /** The shortest it ever took */
+    best: number;
+    /** When it was won, in milliseconds since 1970 */
+    finished: number;
+}
+/**
+ * How far a campaign has got, as plain data to keep between games: the mission it is at, the missions won and how
+ * long each took, the heroes carried out of the last one won, and the game's own state of it (`data`, of the type
+ * `D` the campaign says: choices made, gold saved up, the units that go on; what each mission won carries, merged in).
+ * It says which format it is in, so that what was kept is read again when the format changes
+ *
+ * @beta
+ */
+export interface CampaignProgress<D extends object = Record<string, unknown>> {
+    format: number;
+    /** The campaign it is of, by id */
+    campaign: string;
+    /** The mission to play next */
+    at: string;
+    /** The difficulty chosen for it (`CampaignDef.difficulties`), by name: its missions' computers play on it */
+    difficulty?: string;
+    /** Missions won, by id */
+    done: Record<string, MissionResult>;
+    /** The heroes carried into the next mission */
+    heroes: HeroRecord[];
+    /** The game's own, plain data: what the missions won carried (`MissionDef.carry`), each mission's keys over the ones before */
+    data: Partial<D>;
+}
+/**
+ * A campaign as it is before anything is played: at its first mission, with nothing carried
+ *
+ * @beta
+ */
+export declare function newCampaignProgress<D extends object = Record<string, unknown>>(campaign: string, first: string): CampaignProgress<D>;
+/**
+ * Progress as it was kept, checked and brought up to date. Throws on what is wrong
+ *
+ * @beta
+ */
+export declare function readCampaignProgress(data: unknown): CampaignProgress;
+/**
+ * A mission won: how long it took, the best time kept, the heroes it ends with to carry on, the campaign at the
+ * mission after it (`next`), or still at this one when it was the last, and what it carries of the game's own
+ * (`data`: its keys over the ones kept, the rest kept as they were). A new progress: the one given is left as it was
+ *
+ * @beta
+ */
+export declare function missionWon<D extends object = Record<string, unknown>>(progress: CampaignProgress<D>, mission: string, seconds: number, heroes: HeroRecord[], next?: string, data?: Partial<D>): CampaignProgress<D>;
+/**
+ * A unit as plain data, to take from one mission into the next (`carryUnits`, `placeUnits`): what it is, the name the
+ * rules knew it by, how much of its health it has (a share, 0 to 1), its veterancy (`withVeterancy`) and its items
+ * slot by slot. Not where it is: the next mission says where they come in. Heroes are carried as heroes (`carryOut`)
+ *
+ * @beta
+ */
+export interface UnitRecord {
+    /** Its unit type */
+    type: string;
+    /** The name it was known by in the rules (`world.named`), when it had one */
+    name?: string;
+    /** Its health, a share of the most it has: 1 for whole */
+    health: number;
+    /** Its experience and rank, where it has earned some (`withVeterancy`) */
+    veterancy?: VeterancyState;
+    /** Its inventory slot by slot, where it has one: null for an empty slot */
+    items?: (HeroItem | null)[];
+}
+/**
+ * A player's units as records to carry on (`UnitRecord`): those alive, not structures, not heroes (`carryOut` carries
+ * those), and of them what `filter` keeps (the footmen, the three nearest the gate). In the order of their ids
+ *
+ * @beta
+ */
+export declare function carryUnits(world: World, player: PlayerId, filter?: (unit: Entity) => boolean): UnitRecord[];
+/**
+ * Brings carried units into a mission for a player, round a point (`spread` apart, in rings: 1.5 when left out), each
+ * with its name, its share of health, its veterancy and its items. What the game no longer has, a type or an item, is
+ * left out. The units made, in the order of the records
+ *
+ * @beta
+ */
+export declare function placeUnits(world: World, player: PlayerId, records: readonly UnitRecord[], at: Vec2, spread?: number): Entity[];
+/**
+ * What a player has researched, to carry on (`giveResearch`): each upgrade's level, by its id
+ *
+ * @beta
+ */
+export declare function carryResearch(world: World, player: PlayerId): Record<string, number>;
+/**
+ * Gives a player research carried in (`carryResearch`): each upgrade up to its level, never down, no further than it
+ * goes, and what it does besides stats (`UpgradeDef.apply`) to the units the player has, as research finishing does.
+ * What the game no longer has is left out
+ *
+ * @beta
+ */
+export declare function giveResearch(world: World, player: PlayerId, research: Readonly<Record<string, number>>): void;
+/**
+ * What a player has of each resource, to carry on (`giveResources`): a copy, all of it, or of the kinds named
+ *
+ * @beta
+ */
+export declare function carryResources(world: World, player: PlayerId, kinds?: readonly string[]): Purse;
+/**
+ * Gives a player resources carried in (`carryResources`), on top of what the mission starts it with. What the game no
+ * longer has is left out
+ *
+ * @beta
+ */
+export declare function giveResources(world: World, player: PlayerId, resources: Readonly<Purse>): void;
+/**
+ * The heroes of a player as records to carry on (see `heroRecord`): fallen ones too, as a campaign brings them back
+ *
+ * @beta
+ */
+export declare function carryOut(world: World, player: PlayerId): HeroRecord[];
+/**
+ * Brings carried heroes into a mission for a player. Each takes the place of the hero the map has for it: the one of
+ * that player under the same name, else one of that player of the same type; a hero the map has none for is made at
+ * `at`. The heroes, in the order of the records
+ *
+ * @beta
+ */
+export declare function carryIn(world: World, heroes: readonly HeroRecord[], player: PlayerId, at: Vec2): Entity[];

package/dist/packs/heroes/carry.d.ts

@@ -0,0 +1,59 @@
+import type { Entity, PlayerId } from '#engine/entity';
+import type { Vec2 } from '#engine/math';
+import type { SpawnOptions, World } from '#engine/world';
+/**
+ * An item a hero carries, as it is carried over: what it is, its uses left, the game's own state of it
+ *
+ * @beta
+ */
+export interface HeroItem {
+    item: string;
+    charges: number;
+    data?: Record<string, unknown>;
+}
+/**
+ * A hero as plain data, to take from one world into another: a campaign's hero going on to the next mission with all
+ * it has earned. Its level and experience, the points it has not spent, the abilities it learned and how far, and its
+ * items slot by slot. Not where it is or how hurt: the next mission puts it where it starts, whole
+ *
+ * @beta
+ */
+export interface HeroRecord {
+    /** Its unit type */
+    type: string;
+    /** The name it was known by in the rules (`world.named`), when it had one */
+    name?: string;
+    level: number;
+    xp: number;
+    points: number;
+    /** Learned abilities and their level. Ones not learned are left out */
+    abilities: Record<string, number>;
+    /** Its inventory slot by slot: null for an empty slot */
+    items: (HeroItem | null)[];
+}
+/**
+ * A hero of a world as a record, to carry into another (see `applyHeroRecord`). Throws for what is no hero
+ *
+ * @beta
+ */
+export declare function heroRecord(world: World, hero: Entity): HeroRecord;
+/**
+ * Makes a hero of a world what a record says it was: its level, experience and points, its abilities as far as they
+ * were learned, and its items in their slots. In place of what it had. What the game no longer has, an ability or an
+ * item, is left out. Whole: health and mana full, nothing cooling down
+ *
+ * @beta
+ */
+export declare function applyHeroRecord(world: World, hero: Entity, record: HeroRecord): void;
+/**
+ * A hero made from a record (see `heroRecord`) for a player at a point, under the name it had unless told another
+ *
+ * @beta
+ */
+export declare function heroFromRecord(world: World, record: HeroRecord, owner: PlayerId, at: Vec2, options?: SpawnOptions): Entity;
+/**
+ * A record read back from what was kept (a campaign's progress, a file), checked. Throws on what is wrong
+ *
+ * @beta
+ */
+export declare function readHeroRecord(data: unknown): HeroRecord;

package/dist/packs/heroes/commands.d.ts

@@ -0,0 +1,6 @@
+declare module '#engine/commands' {
+    interface Commands {
+        heroes: (typeof heroCommands)[number];
+    }
+}
+export {};

package/dist/packs/heroes/hire.d.ts

@@ -0,0 +1,9 @@
+import type { Entity, PlayerId } from '#engine/entity';
+import type { World } from '#engine/world';
+/**
+ * Hires a unit at a place that hires for a player: a tavern's hero, a dock's boat. Paid for, and made next to the
+ * place, a boat on the water nearest it. The unit, or nothing with the player told why
+ *
+ * @beta
+ */
+export declare function hire(world: World, shop: Entity, unit: string, player: PlayerId): Entity | undefined;

package/dist/packs/heroes/index.d.ts

@@ -0,0 +1,12 @@
+import { type HeroesPack, type HeroRules } from '#engine/hero';
+/**
+ * The heroes pack: what makes a game a classic hero RTS, opted into (`GameModule.packs: [withHeroes()]`). Heroes, with
+ * their experience, levels, points and abilities to learn, brought back at an altar (`revive`); creeps' camps that guard
+ * their ground, sleep at night and come back (`Camp.respawn`); shops that sell (`buy`, `sell`) and places that hire
+ * (`hire`). `rules` change its numbers (`HeroRules`: how many heroes, the experience a level takes), the classic RTS numbers for
+ * those left out. A game without it pays nothing for any of it: no hero is made of a hero's type, no command of these
+ * is taken, no camp is looked at
+ *
+ * @beta
+ */
+export declare function withHeroes(rules?: Partial<HeroRules>): HeroesPack;

package/dist/packs/heroes/making.d.ts

@@ -0,0 +1,16 @@
+/**
+ * What the heroes pack does as heroes are made and as things die: a hero of a hero's type made one, and the
+ * experience of a kill shared out (the pack's `made` and `death` handlers)
+ */
+import type { Entity } from '#engine/entity';
+import type { World } from '#engine/world';
+/**
+ * Makes a unit just made a hero, as its type says (`UnitTypeDef.hero`): level 1, a point to spend, the abilities it can
+ * learn (none learned) and the spells it starts with, those it has not got already. What `World.spawn` does for a
+ * hero's type, and `morph` for what becomes one
+ *
+ * @beta
+ */
+export declare function makeHero(world: World, entity: Entity): void;
+/** Shares the experience for a kill between the heroes of the killer's side that were around */
+export declare function awardKill(world: World, dead: Entity, killer: Entity | undefined): void;

package/dist/packs/heroes/respawn.d.ts

@@ -0,0 +1,42 @@
+import type { AbilityDef } from '#engine/defs';
+import type { GamePack } from '#engine/packs/pack';
+import type { Entity } from '#engine/entity';
+import type { Vec2 } from '#engine/math';
+import type { World } from '#engine/world';
+/**
+ * What a game's heroes do once fallen (`withRespawn`)
+ *
+ * @beta
+ */
+export interface RespawnOptions {
+    /** Seconds a fallen hero waits to come back: 4 and 2 more a level when left out (6 at level 1, 24 at level 10) */
+    time?: (world: World, hero: Entity) => number;
+    /** Where it comes back: its side's home (`homeOf`) when left out, where it fell when there is none */
+    at?: (world: World, hero: Entity) => Vec2 | undefined;
+    /** Which heroes come back by themselves: all of them when left out */
+    heroes?: (world: World, hero: Entity) => boolean;
+}
+/**
+ * A game whose heroes come back by themselves after a while, at their side's home (see `RespawnOptions`): a saved timer
+ * each, shown on the HUD as a revive is, and waited for by the computer player in place of reviving at an altar.
+ * Revived at an altar in the meantime, it is back then, and the timer comes to nothing. For a game with the heroes pack
+ * on (`withHeroes()`): one without it is refused
+ *
+ * @beta
+ */
+export declare function withRespawn(options?: RespawnOptions): GamePack;
+/**
+ * Recall (features-plan F2): a hero stands and channels for a few seconds, then is at its side's home (`homeOf`),
+ * however far; hurt in the meantime, or told to do something else, and it stays where it is. An ability to give heroes
+ * (`UnitTypeDef.abilities`), made of the engine's parts: a channel (`AbilityDef.channel`) that `breaksOnDamage`, and the
+ * `teleport` effect when it is `finished`. Its id, name, how long it takes, its cooldown and key are the game's to say
+ *
+ * @beta
+ */
+export declare function recallAbility(options?: {
+    id?: string;
+    name?: string;
+    duration?: number;
+    cooldown?: number;
+    hotkey?: string;
+}): AbilityDef;

package/dist/packs/moba/index.d.ts

@@ -0,0 +1,34 @@
+import type { DamageType, Stats } from '#engine/defs';
+import type { GamePack } from '#engine/packs/pack';
+/**
+ * The MOBA stats pack's id
+ *
+ * @beta
+ */
+export declare const MOBA_STATS = "core.mobaStats";
+/**
+ * What the MOBA stats pack is made with (`withMobaStats`)
+ *
+ * @beta
+ */
+export interface MobaStatsOptions {
+    /** What a critical strike multiplies the damage by, for units that do not say: 1.75 when left out */
+    critDamage?: number;
+    /** Tenacity no unit goes past: what is left of a stun or a slow at the very least. 0.9 when left out */
+    maxTenacity?: number;
+}
+/**
+ * What is left of damage once the target's armor or magic resist, less what the source's penetration ignores, had its
+ * say: the pack's `rules.combat.mitigation`
+ *
+ * @beta
+ */
+export declare function penetratingMitigation(type: DamageType, target: Readonly<Stats>, source?: Readonly<Stats>): number;
+/**
+ * The stats of a MOBA, for a game that has them: ability power (what `scaling: { abilityPower }` reads), critical
+ * strikes, armor and magic penetration, life steal and omnivamp, tenacity, slow resistance, heal and shield power,
+ * ability haste, with the hero arena games' formulas for each. A game without it has none of these stats
+ *
+ * @beta
+ */
+export declare function withMobaStats(options?: MobaStatsOptions): GamePack;

package/dist/packs/pack.d.ts

@@ -0,0 +1,84 @@
+import type { EffectKind } from '#engine/abilities/effects';
+import type { CommandDef } from '#engine/commands';
+import type { Component } from '#engine/components';
+import type { ListenerDef } from '#engine/events';
+import type { HookDef } from '#engine/hooks';
+import type { OrderBehavior, SystemDef } from '#engine/registry';
+import type { StatPart } from '#engine/stats';
+import type { StatDef } from '#engine/defs';
+import type { EventKey } from '#engine/events';
+import type { ReplicatedEvent, SnapshotPart } from '#engine/replication';
+import type { PlayerId } from '#engine/entity';
+import type { GameMap } from '#engine/map';
+import type { MapProblem } from '#engine/mapFields';
+import type { Registry } from '#engine/registry';
+import type { GameRules, RulesInit } from '#engine/rules';
+import type { World } from '#engine/world';
+import type { TimerDef } from '#engine/timers';
+/**
+ * A part of the rules a game opts into (`GameModule.packs`): commands, orders, systems, hooks and the state it keeps,
+ * which a game without it pays nothing for. The engine's heroes, camps and shops are one (`withHeroes`). A game's
+ * own lists come after a pack's, so a command, an order, a hook or a system of the same id or name takes its place;
+ * `withoutCommands`, `withoutOrders`, `withoutSystems` and `withoutHooks` take one of a pack's out as they do the
+ * engine's
+ *
+ * @beta
+ */
+export interface GamePack {
+    /** Unique among a game's packs: how a game, a mod or the editor asks whether it is on (`hasPack`) */
+    id: string;
+    /** Commands it takes, beside the engine's (`defineCommand`) */
+    commands?: CommandDef[];
+    /** Orders its units can be given, beside the engine's */
+    orders?: OrderBehavior[];
+    /** Systems, run with the engine's in the phase each says (see `System`) */
+    systems?: SystemDef[];
+    /** Its handlers of hooks, after the engine's and before the game's (`defineHook`) */
+    hooks?: HookDef[];
+    /** Kinds of ability effects it brings (`defineEffect`), beside the engine's: one of the game's of the same type takes its place */
+    effects?: EffectKind[];
+    /** How it reacts to events (`defineListener`) */
+    listeners?: ListenerDef[];
+    /** The state it keeps on entities, players and the world (`defineComponent`) */
+    components?: Component<any>[];
+    /** What it sets to go off later (`defineTimer`): listed, so that a save finds them by id */
+    timers?: TimerDef[];
+    /** The stats it brings, next to the engine's and the game's own (`StatDef`, as `GameModule.stats`) */
+    stats?: StatDef[];
+    /** What it adds to a unit's stats, kept up to date as the engine keeps the rest (`StatPart`) */
+    statParts?: StatPart[];
+    /** The events it tells of (`defineEvent`), listed as a game's are */
+    events?: EventKey<any>[];
+    /** How events of the world of its own are told to the players (`replicateEvent`), after the engine's */
+    replications?: ReplicatedEvent[];
+    /** Parts of the players' snapshots of its own (`SnapshotPart`), after the engine's */
+    snapshotParts?: SnapshotPart[];
+    /** What it adds to the game's report of a player at the end (`GameModule.report`), beside the game's own */
+    report?(world: World, player: PlayerId): Record<string, unknown>;
+    /** How a game with it is won, where the game says nothing of its own (`GameModule.victory`): the last pack's that says */
+    victory?: SystemDef | null;
+    /**
+     * The rules it changes: handed the game's as they come out (the engine's, the game's over them, the packs' before it),
+     * it gives what it lays over them. A function of them, so that what it says can be made of what was there (the lanes'
+     * supply: none for a minion, the game's own for the rest)
+     */
+    rules?(rules: Readonly<GameRules>): RulesInit;
+    /** What it finds wrong with a map in the editor, beside what the game finds (`MapEditorDef.check`) */
+    check?(map: GameMap, registry: Registry): MapProblem[];
+    /** The packs it is made to go with, by id: a game with it and without one of them is refused */
+    requires?: string[];
+    /**
+     * What it was made with, as plain data: what a game's hash names it by, beside its id (`gameHash`), so that one pack
+     * made two ways is two games
+     */
+    options?: unknown;
+}
+/**
+ * Whether a game has a pack on, by its id: `hasPack(game, HEROES)`, what the editor asks before it shows a hero's
+ * fields
+ *
+ * @beta
+ */
+export declare function hasPack(game: {
+    packs?: readonly GamePack[];
+} | null | undefined, id: string): boolean;