@screeps-arena-community/types 1.0.0

package/src/game/prototypes/container.d.ts

@@ -0,0 +1,14 @@
+declare module 'game/prototypes/container' {
+  import { Store } from 'game/prototypes/store'
+  import { OwnedStructure } from 'game/prototypes/owned-structure'
+
+  /**
+   * A small container that can be used to store resources.
+   * This is a walkable structure.
+   * All dropped resources automatically goes to the container at the same tile.
+   */
+  export class StructureContainer extends OwnedStructure {
+    /** A {@link Store} object that contains cargo of this structure. */
+    store: Store
+  }
+}

package/src/game/prototypes/creep.d.ts

@@ -0,0 +1,272 @@
+declare module 'game/prototypes/creep' {
+  import { Direction, FindPathOptions } from 'game/utils'
+  import {
+    OK,
+    ERR_NOT_OWNER,
+    ERR_NOT_ENOUGH_RESOURCES,
+    ERR_INVALID_TARGET,
+    ERR_FULL,
+    ERR_NOT_IN_RANGE,
+    ERR_INVALID_ARGS,
+    ERR_TIRED,
+    ERR_NO_BODYPART,
+    ATTACK,
+    CARRY,
+    HEAL,
+    MOVE,
+    RANGED_ATTACK,
+    WORK,
+  } from 'game/constants'
+
+  import { findPath } from 'game/utils'
+  import { Position } from 'game/utils'
+  import { GameObject } from 'game/prototypes/game-object'
+  import { Structure } from 'game/prototypes/structure'
+  import { ConstructionSite } from 'game/prototypes/construction-site'
+  import { Resource, ResourceType } from 'game/prototypes/resource'
+  import { Source } from 'game/prototypes/source'
+  import { Store } from 'game/prototypes/store'
+
+  type BodyPartType =
+    | typeof ATTACK
+    | typeof CARRY
+    | typeof HEAL
+    | typeof MOVE
+    | typeof RANGED_ATTACK
+    | typeof TOUGH
+    | typeof WORK
+
+  type CreepAttackResult =
+    | typeof OK
+    | typeof ERR_NOT_OWNER
+    | typeof ERR_NO_BODYPART
+    | typeof ERR_INVALID_TARGET
+    | typeof ERR_NOT_IN_RANGE
+
+  type CreepBuildResult =
+    | typeof OK
+    | typeof ERR_NOT_OWNER
+    | typeof ERR_NO_BODYPART
+    | typeof ERR_NOT_ENOUGH_RESOURCES
+    | typeof ERR_INVALID_TARGET
+    | typeof ERR_FULL
+    | typeof ERR_NOT_IN_RANGE
+
+  type CreepDropResult =
+    | typeof OK
+    | typeof ERR_NOT_OWNER
+    | typeof ERR_INVALID_ARGS
+    | typeof ERR_NOT_ENOUGH_RESOURCES
+
+  type CreepHarvestResult =
+    | typeof OK
+    | typeof ERR_NOT_OWNER
+    | typeof ERR_NO_BODYPART
+    | typeof ERR_INVALID_TARGET
+    | typeof ERR_NOT_ENOUGH_RESOURCES
+    | typeof ERR_NOT_IN_RANGE
+
+  type CreepHealResult =
+    | typeof OK
+    | typeof ERR_NOT_OWNER
+    | typeof ERR_NO_BODYPART
+    | typeof ERR_INVALID_TARGET
+    | typeof ERR_NOT_IN_RANGE
+
+  type CreepMoveResult =
+    | typeof OK
+    | typeof ERR_NOT_OWNER
+    | typeof ERR_NO_BODYPART
+    | typeof ERR_TIRED
+    | typeof ERR_INVALID_ARGS
+
+  type CreepPickupResult =
+    | typeof OK
+    | typeof ERR_NOT_OWNER
+    | typeof ERR_INVALID_TARGET
+    | typeof ERR_FULL
+    | typeof ERR_NOT_IN_RANGE
+
+  type CreepPullResult =
+    | typeof OK
+    | typeof ERR_NOT_OWNER
+    | typeof ERR_NO_BODYPART
+    | typeof ERR_TIRED
+    | typeof ERR_INVALID_TARGET
+    | typeof ERR_NOT_IN_RANGE
+
+  type CreepRangedAttackResult =
+    | typeof OK
+    | typeof ERR_NOT_OWNER
+    | typeof ERR_NO_BODYPART
+    | typeof ERR_INVALID_TARGET
+    | typeof ERR_NOT_IN_RANGE
+
+  type CreepRangedHealResult =
+    | typeof OK
+    | typeof ERR_NOT_OWNER
+    | typeof ERR_NO_BODYPART
+    | typeof ERR_INVALID_TARGET
+    | typeof ERR_NOT_IN_RANGE
+
+  type CreepRangedMassAttackResult =
+    | typeof OK
+    | typeof ERR_NOT_OWNER
+    | typeof ERR_NO_BODYPART
+
+  type CreepTransferResult =
+    | typeof OK
+    | typeof ERR_NOT_OWNER
+    | typeof ERR_INVALID_ARGS
+    | typeof ERR_INVALID_TARGET
+    | typeof ERR_NOT_IN_RANGE
+    | typeof ERR_FULL
+    | typeof ERR_NOT_ENOUGH_RESOURCES
+
+  type CreepWithdrawResult =
+    | typeof OK
+    | typeof ERR_NOT_OWNER
+    | typeof ERR_INVALID_ARGS
+    | typeof ERR_INVALID_TARGET
+    | typeof ERR_NOT_IN_RANGE
+    | typeof ERR_FULL
+    | typeof ERR_NOT_ENOUGH_RESOURCES
+
+  /**
+   * Creeps are units that can move, harvest energy, construct structures, attack another creeps, and perform other actions.
+   * @extends GameObject
+   */
+  export class Creep extends GameObject {
+    /** An array describing the creep’s body */
+    body: Array<{ type: BodyPartType; hits: number }>
+
+    /** The movement fatigue indicator. If it is greater than zero, the creep cannot move */
+    fatigue: number
+
+    /** The current amount of hit points of the creep */
+    hits: number
+
+    /** The maximum amount of hit points of the creep */
+    hitsMax: number
+
+    /** Whether it is your creep */
+    my: boolean
+
+    /** A {@link Store} object that contains cargo of this creep */
+    store: Store
+
+    /** Whether this creep is still being spawned */
+    spawning: boolean
+
+    /**
+     * Attack another creep, structure, or construction site in a short-ranged attack. Requires the {@link ATTACK} body part
+     * @param target The target object
+     * @returns Either {@link OK} or one of ERR_* error codes
+     */
+    attack(target: Creep | Structure | ConstructionSite): CreepAttackResult
+
+    /**
+     * Build a structure at the target construction site using carried energy.
+     * Requires {@link WORK} and {@link CARRY} body parts
+     * @param target The target construction site to be built
+     * @returns Either {@link OK} or one of ERR_* error codes
+     */
+    build(target: ConstructionSite): CreepBuildResult
+
+    /**
+     * Drop a resource on the ground
+     * @param resource One of the RESOURCE_* constants
+     * @param amount The amount of resource units to be dropped. If omitted, all the available carried amount is used
+     * @returns Either {@link OK} or one of ERR_* error codes
+     */
+    drop(resource: ResourceType, amount?: number): CreepDropResult
+
+    /**
+     * Harvest energy from the source. Requires the {@link WORK} body part
+     * @param target The object to be harvested
+     * @returns Either {@link OK} or one of ERR_* error codes
+     */
+    harvest(target: Source): CreepHarvestResult
+
+    /**
+     * Heal self or another creep nearby. Requires the {@link HEAL} body part.
+     * @param target The target creep object
+     * @returns Either {@link OK} or one of ERR_* error codes
+     */
+    heal(target: Creep): CreepHealResult
+
+    /**
+     * Move the creep one square in the specified direction. Requires the {@link MOVE} body part
+     * @param direction The direction to move
+     * @returns Either {@link OK} or one of ERR_* error codes
+     */
+    move(direction: Direction): CreepMoveResult
+
+    /**
+     * Find the optimal path to the target and move to it. Requires the {@link MOVE} body part
+     * @param target The target to move to. Can be a {@link GameObject} or any object containing x and y properties.
+     * @param options An object with additional options that are passed to {@link findPath}
+     * @returns Either {@link OK} or one of ERR_* error codes
+     */
+    moveTo(target: Position, options?: FindPathOptions): CreepMoveResult
+
+    /**
+     * Pick up an item (a dropped piece of resource). Requires the {@link CARRY} body part.
+     * @param target The target object to be picked up
+     * @returns Either {@link OK} or one of ERR_* error codes
+     */
+    pickup(target: Resource): CreepPickupResult
+
+    /**
+     * Help another creep to follow this creep. Requires the {@link MOVE} body part
+     * @param target The target creep
+     * @returns Either {@link OK} or one of ERR_* error codes
+     */
+    pull(target: Creep): CreepPullResult
+
+    /**
+     * A ranged attack against another creep or structure. Requires the {@link RANGED_ATTACK} body part
+     * @param target The target object to be attacked
+     * @returns Either {@link OK} or one of ERR_* error codes
+     */
+    rangedAttack(target: Creep | Structure): CreepRangedAttackResult
+
+    /**
+     * Heal another creep at a distance. Requires the {@link HEAL} body part
+     * @param target The target creep object
+     * @returns Either {@link OK} or one of ERR_* error codes
+     */
+    rangedHeal(target: Creep): CreepRangedHealResult
+
+    /**
+     * A ranged attack against all hostile creeps or structures within 3 squares range.  Requires the {@link RANGED_ATTACK} body part
+     * @returns Either {@link OK} or one of ERR_* error codes
+     */
+    rangedMassAttack(): CreepRangedMassAttackResult
+
+    /**
+     * Transfer resource from the creep to another object
+     * @param target The target object
+     * @param resource One of the RESOURCE_* constants
+     * @param amount The amount of resources to be transferred. If omitted, all the available carried amount is used
+     */
+    transfer(
+      target: Structure | Creep,
+      resource: ResourceType,
+      amount?: number
+    ): CreepTransferResult
+
+    /**
+     * Withdraw resources from a structure
+     * @param target The target structure
+     * @param resource One of the RESOURCE_* constants
+     * @param amount The amount of resources to be transferred. If omitted, all the available carried amount is used
+     * @returns Either {@link OK} or one of ERR_* error codes
+     */
+    withdraw(
+      target: Structure,
+      resource: ResourceType,
+      amount?: number
+    ): CreepWithdrawResult
+  }
+}

package/src/game/prototypes/extension.d.ts

@@ -0,0 +1,10 @@
+declare module 'game/prototypes/extension' {
+  import { Store } from 'game/prototypes/store'
+  import { OwnedStructure } from 'game/prototypes/owned-structure'
+
+  /** Contains energy that can be spent on spawning bigger creeps */
+  export class StructureExtension extends OwnedStructure {
+    /** A {@link Store} object that contains cargo of this structure. */
+    store: Store
+  }
+}

package/src/game/prototypes/flag.d.ts

@@ -0,0 +1,9 @@
+declare module 'game/prototypes/flag' {
+  import { GameObject } from 'game/prototypes'
+
+  /** A flag is a key game object for this arena. Capture all flags to win the game */
+  export class Flag extends GameObject {
+    /** Equals to true or false if the flag is owned. Returns undefined if it is neutral */
+    readonly my?: boolean
+  }
+}

package/src/game/prototypes/game-object.d.ts

@@ -0,0 +1,110 @@
+import { SearchPathOptions } from '../path-finder'
+
+declare module 'game/prototypes/game-object' {
+  import { getObjectById, FindPathOptions } from 'game/utils'
+
+  import { findPath } from 'game/utils' // eslint-disable-line @typescript-eslint/no-unused-vars
+
+  /** Position of object in the room */
+  export type Position = {
+    /** The X coordinate in the room */
+    x: number
+
+    /** The Y coordinate in the room */
+    y: number
+  }
+
+  export type EffectData = {
+    /** The effect multiplier */
+    multiplier: number
+  }
+
+  /** Represents an effect applied to a game object */
+  export class Effect {
+    /** The effect type */
+    effectType: string
+    /** The effect data */
+    data: EffectData
+  }
+
+  /**
+   * Basic prototype for game objects.
+   * All objects and classes are inherited from this class
+   */
+  export class GameObject extends Position {
+    /** true if this object is live in the game at the moment */
+    exists: boolean
+
+    /** The unique ID of this object that you can use in {@link getObjectById} */
+    id: number | string
+
+    /** If defined, then this object will disappear after this number of ticks*/
+    ticksToDecay?: number
+
+    /** The X coordinate in the room */
+    x: number
+
+    /** The Y coordinate in the room */
+    y: number
+
+    /** An array with the effects applied to this object */
+    effects?: Effect[] | null
+
+    /**
+     * Find a position with the shortest path from this game object
+     * @param positions The positions to search among. An array of {@link GameObject} or any objects containing x and y properties
+     * @param options An object containing additional pathfinding flags
+     * @param options.costMatrix Custom navigation cost data
+     * @param options.plainCost Cost for walking on plain positions. The default is 2
+     * @param options.swampCost Cost for walking on swamp positions. The default is 10
+     * @param options.flee Instead of searching for a path to the goals this will search for a path away from the goals. The default is false
+     * @param options.maxOps The maximum allowed pathfinding operations. The default value is 50000
+     * @param options.maxCost The maximum allowed cost of the path returned. The default is Infinity
+     * @param options.heuristicWeight Weight from 1 to 9 to apply to the heuristic in the A* formula F = G + weight * H. The default value is 1.2
+     * @param options.ignore objects which should not be treated as obstacles during the search
+     * @returns the closest object from {@link positions}, or null if there was no valid positions
+     */
+    findClosestByPath<T extends Position>(
+      positions: T[],
+      options?: FindPathOptions
+    ): T
+
+    /**
+     * Find a position with the shortest linear distance from this game object
+     * @param positions The positions to search among. An array of {@link GameObject} or any objects containing x and y properties
+     * @returns the closest object from {@link positions}
+     */
+    findClosestByRange<T extends Position>(positions: T[]): T
+
+    /**
+     * Find all objects in the specified linear range
+     * @param positions The positions to search. An array of {@link GameObject} or any objects containing x and y properties
+     * @param range The range distance
+     * @returns an array with the objects found
+     */
+    findInRange<T extends Position>(positions: T[], range: number): T[]
+
+    /**
+     * Find a path from this object to the given position
+     * @param pos The target position. May be {@link GameObject} or any object containing x and y properties
+     * @param options An object with additional options that are passed to {@link findPath}
+     * @param options.costMatrix Custom navigation cost data
+     * @param options.plainCost Cost for walking on plain positions. The default is 2
+     * @param options.swampCost Cost for walking on swamp positions. The default is 10
+     * @param options.flee Instead of searching for a path to the goals this will search for a path away from the goals. The default is false
+     * @param options.maxOps The maximum allowed pathfinding operations. The default value is 50000
+     * @param options.maxCost The maximum allowed cost of the path returned. The default is Infinity
+     * @param options.heuristicWeight Weight from 1 to 9 to apply to the heuristic in the A* formula F = G + weight * H. The default value is 1.2
+     * @param options.ignore objects which should not be treated as obstacles during the search
+     * @returns the path found as an array of objects containing x and y properties
+     */
+    findPathTo(pos: Position, options?: FindPathOptions): Position[]
+
+    /**
+     * Get linear range between this and target object
+     * @param pos The target object. May be {@link GameObject} or any object containing x and y properties
+     * @returns a number of squares between two objects
+     */
+    getRangeTo(pos: Position): number
+  }
+}

package/src/game/prototypes/index.d.ts

@@ -0,0 +1,17 @@
+declare module 'game/prototypes' {
+  export { Creep } from 'game/prototypes/creep'
+  export { GameObject } from 'game/prototypes/game-object'
+  export { Structure } from 'game/prototypes/structure'
+  export { OwnedStructure } from 'game/prototypes/owned-structure'
+  export { StructureTower } from 'game/prototypes/tower'
+  export { StructureSpawn } from 'game/prototypes/spawn'
+  export { StructureWall } from 'game/prototypes/wall'
+  export { StructureContainer } from 'game/prototypes/container'
+  export { Source } from 'game/prototypes/source'
+  export { Resource } from 'game/prototypes/resource'
+  export { StructureRampart } from 'game/prototypes/rampart'
+  export { ConstructionSite } from 'game/prototypes/construction-site'
+  export { StructureExtension } from 'game/prototypes/extension'
+  export { StructureRoad } from 'game/prototypes/road'
+  export { Flag } from 'game/prototypes/flag'
+}

package/src/game/prototypes/owned-structure.d.ts

@@ -0,0 +1,9 @@
+declare module 'game/prototypes/owned-structure' {
+  import { Structure } from 'game/prototypes/structure'
+
+  /** The base prototype for a structure that has an owner */
+  export abstract class OwnedStructure extends Structure {
+    /** true for your structure, false for a hostile structure, undefined for a neutral structure */
+    readonly my?: boolean
+  }
+}

package/src/game/prototypes/rampart.d.ts

@@ -0,0 +1,6 @@
+declare module 'game/prototypes/rampart' {
+  import { OwnedStructure } from 'game/prototypes/owned-structure'
+
+  /** Blocks movement of hostile creeps, and defends your creeps and structures on the same position. */
+  export class StructureRampart extends OwnedStructure {}
+}

package/src/game/prototypes/resource.d.ts

@@ -0,0 +1,14 @@
+declare module 'game/prototypes/resource' {
+  import { GameObject } from 'game/prototypes/game-object'
+
+  type ResourceType = string // TODO: develop resource type
+
+  /** A dropped piece of resource. Dropped resource pile decays for ceil(amount/1000) units per tick */
+  export class Resource extends GameObject {
+    /** The amount of dropped resource */
+    amount: number
+
+    /** The type of dropped resource (one of RESOURCE_* constants) */
+    resourceType: ResourceType
+  }
+}

package/src/game/prototypes/road.d.ts

@@ -0,0 +1,6 @@
+declare module 'game/prototypes/road' {
+  import { Structure } from 'game/prototypes/structure'
+
+  /** Decreases movement cost to 1. Using roads allows creating creeps with less MOVE body parts */
+  export class StructureRoad extends Structure {}
+}

package/src/game/prototypes/source.d.ts

@@ -0,0 +1,13 @@
+declare module 'game/prototypes/source' {
+  import { WORK } from 'game/constants' // eslint-disable-line @typescript-eslint/no-unused-vars
+  import { GameObject } from 'game/prototypes/game-object'
+
+  /** An energy source object. Can be harvested by creeps with a {@link WORK} body part */
+  export class Source extends GameObject {
+    /** Current amount of energy in the source */
+    energy: number
+
+    /** The maximum amount of energy in the source */
+    energyCapacity: number
+  }
+}

package/src/game/prototypes/spawn.d.ts

@@ -0,0 +1,73 @@
+declare module 'game/prototypes/spawn' {
+  import {
+    OK,
+    ERR_NOT_OWNER,
+    ERR_BUSY,
+    ERR_INVALID_ARGS,
+    ERR_NOT_ENOUGH_ENERGY,
+  } from 'game/constants'
+
+  import { BodyPartType } from 'game/prototypes/creep'
+  import { Creep } from 'game/prototypes/creep'
+  import { Store } from 'game/prototypes/store'
+  import { OwnedStructure } from 'game/prototypes/owned-structure'
+
+  /** {@link createConstructionSite} call result*/
+  export interface SpawnCreepResult {
+    /** the instance of the {@link Creep} being spawned */
+    object?: Creep | undefined
+
+    /** the error code */
+    error?:
+      | typeof ERR_NOT_OWNER
+      | typeof ERR_INVALID_ARGS
+      | typeof ERR_NOT_ENOUGH_ENERGY
+      | typeof ERR_BUSY
+      | undefined
+  }
+
+  type SetDirectionsResult =
+    | typeof OK
+    | typeof ERR_NOT_OWNER
+    | typeof ERR_INVALID_ARGS
+
+  /** Details of the creep being spawned currently */
+  export class Spawning {
+    /** Time needed in total to complete the spawning */
+    needTime: number
+
+    /** Remaining time to go */
+    remainingTime: number
+
+    /** The creep that being spawned */
+    creep: Creep
+
+    /** Cancel spawning immediately */
+    cancel(): typeof OK | typeof ERR_NOT_OWNER | undefined
+  }
+
+  /** This structure can create creeps. It also auto-regenerate a little amount of energy each tick */
+  export class StructureSpawn extends OwnedStructure {
+    /** A {@link Store} object that contains cargo of this structure */
+    store: Store
+
+    /** If the spawn is in process of spawning a new creep, this object will contain a {@link Spawning} object, or null otherwise */
+    spawning: Spawning
+
+    /** The directions in which the spawn can create creeps */
+    directions: DirectionConstant[]
+
+    /**
+     * Set the directions in which the spawn can create creeps
+     * @param directions An array of direction constants
+     */
+    setDirections(directions: DirectionConstant[]): SetDirectionsResult
+
+    /**
+     * Start the creep spawning process
+     * @param body An array describing the new creep’s body
+     * @returns a {@link SpawnCreepResult} object with the call result
+     */
+    spawnCreep(body: BodyPartType[]): SpawnCreepResult
+  }
+}

package/src/game/prototypes/store.d.ts

@@ -0,0 +1,17 @@
+declare module 'game/prototypes/store' {
+  type ResourceType = string // TODO: develop resource type
+
+  /** An object that class contain resources in its cargo */
+  export type Store = {
+    /** Returns capacity of this store for the specified resource */
+    getCapacity(resource?: ResourceType): number | null
+
+    /** Returns free capacity for the store */
+    getUsedCapacity(resource?: ResourceType): number | null
+
+    /** Returns the capacity used by the specified resource */
+    getFreeCapacity(resource?: ResourceType): number | null
+  } & {
+    [resource: ResourceType]: number
+  }
+}

package/src/game/prototypes/structure.d.ts

@@ -0,0 +1,12 @@
+declare module 'game/prototypes/structure' {
+  import { GameObject } from 'game/prototypes/game-object'
+
+  /** The base prototype object of all structures. */
+  export class Structure extends GameObject {
+    /** The current amount of hit points of the structure */
+    readonly hits?: number
+
+    /** The maximum amount of hit points of the structure */
+    readonly hitsMax?: number
+  }
+}

package/src/game/prototypes/tower.d.ts

@@ -0,0 +1,45 @@
+declare module 'game/prototypes/tower' {
+  import {
+    OK,
+    ERR_NOT_OWNER,
+    ERR_TIRED,
+    ERR_INVALID_TARGET,
+    ERR_NOT_ENOUGH_ENERGY,
+  } from 'game/constants'
+  import { OwnedStructure } from 'game/prototypes/owned-structure'
+  import { Store } from 'game/prototypes/store'
+
+  type TowerAttackResult =
+    | typeof OK
+    | typeof ERR_NOT_OWNER
+    | typeof ERR_TIRED
+    | typeof ERR_INVALID_TARGET
+    | typeof ERR_NOT_ENOUGH_ENERGY
+  type TowerHealResult =
+    | typeof OK
+    | typeof ERR_NOT_OWNER
+    | typeof ERR_TIRED
+    | typeof ERR_INVALID_TARGET
+    | typeof ERR_NOT_ENOUGH_ENERGY
+
+  /** Remotely attacks game objects or heals creeps within its range */
+  export class StructureTower extends OwnedStructure {
+    /** A {@link Store} object that contains cargo of this structure. */
+    store: Store
+
+    /** The remaining amount of ticks while this tower cannot be used */
+    cooldown: number
+
+    /**
+     * Remotely attack any creep or structure in range
+     * @param target The target object
+     */
+    attack(target: Creep | Structure): TowerAttackResult
+
+    /**
+     * Remotely heal any creep in range
+     * @param target The target creep
+     */
+    heal(target: Creep): TowerHealResult
+  }
+}

package/src/game/prototypes/wall.d.ts

@@ -0,0 +1,6 @@
+declare module 'game/prototypes/wall' {
+  import { Structure } from 'game/prototypes/structure'
+
+  /** Blocks movement of all creeps */
+  export class StructureWall extends Structure {}
+}