@v12-engine/engine 0.0.0-stage → 0.1.0

package/dist/hero.d.ts

@@ -0,0 +1,177 @@
+import type { Cost } from './defs';
+import { type Entity, type PlayerId } from './entity';
+import type { Vec2 } from './math';
+import type { World } from './world';
+import type { EntityState, LearnableInfo, XpInfo } from './session/protocol';
+import type { GamePack } from './packs/pack';
+import type { HeroSummary } from './session/protocol';
+/**
+ * The id of the heroes pack (`withHeroes`): `hasPack(game, HEROES)`
+ *
+ * @beta
+ */
+export declare const HEROES = "core.heroes";
+/**
+ * The numbers and formulas of heroes, the heroes pack's (`withHeroes(rules)`): how many heroes a player may
+ * have, how much experience a level takes, what bringing one back costs. The classic RTS numbers for
+ * those left out
+ *
+ * @beta
+ */
+export interface HeroRules {
+    /** Heroes a player can have at once, fallen ones and ones being trained included */
+    maxHeroes: number;
+    /** The level heroes stop at, unless their type says otherwise (`HeroDef.maxLevel`) */
+    maxHeroLevel: number;
+    /** Heroes this close to a kill get a share of the experience */
+    xpRange: number;
+    /** Experience needed in total to be of a level. Level 1 must need none */
+    xpForLevel(level: number): number;
+    /** Experience a kill is worth, for units whose type does not say (`UnitTypeDef.xp`) */
+    killXp(world: World, dead: Entity): number;
+    /** What it costs to bring a fallen hero back, in the game's money, and how long it takes in seconds */
+    revive(world: World, hero: Entity): {
+        cost: Cost;
+        time: number;
+    };
+    /** Ability points a hero gets for reaching a level. One, when left out */
+    pointsForLevel(level: number): number;
+}
+/**
+ * The heroes pack, as `withHeroes` makes it: its rules beside its parts
+ *
+ * @beta
+ */
+export interface HeroesPack extends GamePack {
+    /** What the game says of heroes, over the engine's (`defaultHeroRules`): what the pack was made with (`GameRules.heroes`) */
+    options: Partial<HeroRules>;
+}
+/**
+ * What a hero has earned: its level, its experience, the points it has to put into abilities (`heroState`)
+ *
+ * @beta
+ */
+export interface HeroState {
+    level: number;
+    /** Experience in total */
+    xp: number;
+    /** Points that can be put into abilities */
+    points: number;
+}
+/**
+ * What a player is told of a hero (`heroState`): its level, to everyone who sees it; its experience to its side, and to
+ * everyone where the rules share it (`GameRules.hud.shareXp`); the points it has to spend and what it can learn, to its
+ * side
+ *
+ * @beta
+ */
+export interface HeroSent {
+    level: number;
+    /** Its experience: its side's, and everyone's where the rules share it */
+    xp?: XpInfo;
+    /** Points it has to put into abilities: its side's */
+    points?: number;
+    /** The abilities it can put points into, how far and whether now: its side's */
+    learnable?: LearnableInfo[];
+}
+/**
+ * A hero: what it has earned (`HeroState`). Set as a unit of a type that says it is one (`UnitTypeDef.hero`) is made,
+ * filed by owner (`world.index.with(heroState, player)`, `heroesOf`). What is a hero is what has it: a fallen hero stays
+ * in the world's entities, out of the world, to be brought back
+ *
+ * @beta
+ */
+export declare const heroState: import("./components").Component<HeroState, HeroSent>;
+/**
+ * What a hero has earned: none for what is no hero (`heroState`)
+ *
+ * @beta
+ */
+export declare const heroOf: (entity: Entity) => HeroState | undefined;
+/**
+ * What a player was told of a hero in their snapshot (`heroState`): its level to everyone, its experience, points and
+ * what it can learn to its side. None for what is no hero
+ *
+ * @beta
+ */
+export declare const heroOfState: (state: EntityState) => HeroSent | undefined;
+/**
+ * The level a hero stops at
+ *
+ * @beta
+ */
+export declare const maxLevelOf: (world: World, entity: Entity) => number;
+/**
+ * Gives a hero experience: `from` what was killed, when that is where it comes from. The `beforeXp` hook has its say
+ *
+ * @beta
+ */
+export declare function grantXp(world: World, entity: Entity, amount: number, from?: Entity): void;
+/**
+ * Puts a hero at a level as if it had got there: the points to spend, the stats that grew, the experience of that
+ * level. No message, no event and no `beforeXp`: for a hero that starts a map at that level, not one that earns it.
+ * Never down
+ *
+ * @beta
+ */
+export declare function setHeroLevel(world: World, entity: Entity, level: number): void;
+/**
+ * Experience a kill is worth
+ *
+ * @beta
+ */
+export declare function xpWorth(world: World, entity: Entity): number;
+/**
+ * Hero level needed to put the next point into an ability
+ *
+ * @beta
+ */
+export declare function levelNeeded(world: World, hero: Entity, ability: string): number;
+/**
+ * Whether a hero may put a point into an ability now: by points, levels and its learning, and the `canLearn` hook
+ *
+ * @beta
+ */
+export declare function canLearn(world: World, hero: Entity, ability: string): boolean;
+/** @beta */
+export declare function learn(world: World, hero: Entity, ability: string): boolean;
+/**
+ * Heroes a player has, fallen ones included
+ *
+ * @beta
+ */
+export declare function heroesOf(world: World, player: number): Entity[];
+/**
+ * What it costs to bring a hero back, in the game's money, and how long it takes
+ *
+ * @beta
+ */
+export declare function reviveCost(world: World, hero: Entity): {
+    cost: Cost;
+    time: number;
+};
+/**
+ * Puts a fallen hero back into the world
+ *
+ * @beta
+ */
+export declare function reviveHero(world: World, hero: Entity, at: Vec2): void;
+/**
+ * How long until a fallen hero comes back by itself, in seconds: none for one that is not waiting
+ *
+ * @beta
+ */
+export declare function respawnIn(world: World, hero: Entity): number | undefined;
+/** A hero back, to those who see it */
+export declare const toldRevived: import("./replication").ReplicatedEvent;
+/** A hero's new level, to those who see it */
+export declare const toldLevelUp: import("./replication").ReplicatedEvent;
+/** Experience gained: its side's alone, an enemy sees a bar move, not why */
+export declare const toldXp: import("./replication").ReplicatedEvent;
+/**
+ * A player's heroes, as their portraits show them (`PlayerState.own.heroes`): their level, health and mana, and how far
+ * a fallen one is through being brought back, at an altar or by itself
+ *
+ * @beta
+ */
+export declare function heroSummaries(world: World, player: PlayerId): HeroSummary[];

package/dist/home.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A side's home (`homeOf`): where its heroes come back (`withRespawn`) and are recalled to (an ability's `teleport` to
+ * `home`). Of nothing but the world, so that an ability's effects and the heroes' respawn each read it alone
+ */
+import type { PlayerId } from './entity';
+import { type Vec2 } from './math';
+import type { World } from './world';
+/**
+ * A side's home, where its heroes come back and are recalled to: the map's point named `home.<team>` (`home.1`), or
+ * else the structure of the player's side nearest `near` (its core, its hall), or else nothing
+ *
+ * @beta
+ */
+export declare function homeOf(world: World, player: PlayerId, near?: Vec2): Vec2 | undefined;