mlogjs 0.5.1 → 0.6.0

package/lib/macros.d.ts

@@ -3,6 +3,9 @@
 type MemoryCapacity = 64 | 128 | 512;
 /**
  * Allows you to view and modify the data of memory cells and memory banks.
+ *
+ * @deprecated Use `MemoryView` instead. This class is only kept for backwards
+ *   compatibility and will be removed in a future version.
  */
 declare class Memory<S extends MemoryCapacity = 64> {
   constructor(cell: BasicBuilding, size?: S);
@@ -10,12 +13,21 @@ declare class Memory<S extends MemoryCapacity = 64> {
   [Symbol.iterator](): IterableIterator<number>;
   [index: number]: number;
 
-  /**
-   * The practical length of the memory view.
-   */
+  /** The practical length of the memory view. */
   readonly length: S;
 }
 
+/** Allows you to view and modify the data of memory cells and memory banks. */
+declare class MemoryView<T = number> {
+  constructor(cell: BasicBuilding, size?: number);
+
+  [Symbol.iterator](): IterableIterator<T>;
+  [index: number]: T;
+
+  /** The practical length of the memory view. */
+  readonly length: number;
+}
+
 /**
  * Creates a mutable, dynamic access array, the length is constant.
  *
@@ -36,7 +48,8 @@ declare class MutableArray<T> {
   fill(value: T): void;
 
   /**
-   * Returns the item at the given index. Negative indexes are relative to `this.size`.
+   * Returns the item at the given index. Negative indexes are relative to
+   * `this.size`.
    *
    * ```js
    * print(array.at(-1)); // equal to array[array.size - 1]
@@ -52,7 +65,8 @@ declare class MutableArray<T> {
 
 declare class DynamicArray<T> extends MutableArray<T> {
   /**
-   * Creates an array with a predefined capacity that supports dynamic index accesses.
+   * Creates an array with a predefined capacity that supports dynamic index
+   * accesses.
    *
    * The array can contain any value assignable to a store.
    */
@@ -60,9 +74,11 @@ declare class DynamicArray<T> extends MutableArray<T> {
   constructor(length: number);
 
   /**
-   * Sets the last item of the array to `undefined` and decreases its length by 1.
+   * Sets the last item of the array to `undefined` and decreases its length by
+   * 1.
    *
-   * This method only generates the instructions for getting the value when needed.
+   * This method only generates the instructions for getting the value when
+   * needed.
    *
    * You can use `unchecked` to skip the bound check.
    *
@@ -92,14 +108,14 @@ declare class DynamicArray<T> extends MutableArray<T> {
   /**
    * Removes the item at the given index.
    *
-   * This method only generates the instructions for getting the value when needed.
+   * This method only generates the instructions for getting the value when
+   * needed.
    *
    * The index must be within the range: [`0`, `this.length - 1`]
    *
    * You can use `unchecked` to skip the bound check.
    *
    * ```js
-   *
    * let a = array.removeAt(i); // generates getter instructions
    * array.removeAt(i); // doesn't generate getter instructions
    *
@@ -110,7 +126,8 @@ declare class DynamicArray<T> extends MutableArray<T> {
   removeAt(index: number): T;
 
   /**
-   * Returns the item at the given index. Negative indexes are relative to `this.length`.
+   * Returns the item at the given index. Negative indexes are relative to
+   * `this.length`.
    *
    * ```js
    * print(array.at(-1)); // equal to array[array.length - 1]
@@ -123,28 +140,46 @@ declare class DynamicArray<T> extends MutableArray<T> {
 }
 
 /**
- * A function that tells the compiler not to add
- * bound checking in the array accesses in the given expression.
+ * A function that tells the compiler not to add bound checking in the array
+ * accesses in the given expression.
  *
  * Only access that are computed inside the call are unchecked:
  *
  * ```js
  * // checked
- * const a = array[i]
+ * const a = array[i];
  * // unckecked
- * const b = unchecked(array[i])
+ * const b = unchecked(array[i]);
  *
  * // the array accesses inside `doSomething`
  * // are NOT unchecked
- * unchecked(doSomething(i))
+ * unchecked(doSomething(i));
  *
  * // only `array[i * 2]` is unchecked
- * const c = unchecked(doSomething(i) * array[i * 2])
+ * const c = unchecked(doSomething(i) * array[i * 2]);
  *
  * function doSomething(i) {
- *     // will always be checked
- *     return (array[i - 1] + array[i + 1]) / 2
+ *   // will always be checked
+ *   return (array[i - 1] + array[i + 1]) / 2;
  * }
  * ```
  */
 declare function unchecked<T>(expression: T): T;
+
+/**
+ * A view of a string that allows indexed access to its characters.
+ *
+ * Each character is represented by its UTF-16 code unit.
+ */
+declare class StringView {
+  /**
+   * Creates a view of the given string, allowing you to access its characters
+   * by index.
+   */
+  constructor(string: string);
+
+  [index: number]: number;
+
+  /** The length of the string. */
+  readonly length: number;
+}

package/lib/traits.d.ts

@@ -1,156 +1,318 @@
-import "./globals";
+import { WithSymbols } from "mlogjs:types";
 
-type LogicSymbols = typeof Items & typeof Liquids & typeof LAccess;
+declare global {
+  interface LiquidHolder extends WithSymbols<
+    {
+      readonly [L in keyof typeof Liquids]: number;
+    } & {
+      readonly totalLiquids: number;
+      readonly liquidCapacity: number;
+    }
+  > {}
 
-type WithSymbols<T extends Record<string, unknown>> = T & {
-  readonly [K in keyof (LogicSymbols | T) as LogicSymbols[K]]: T[K];
-};
+  interface ItemHolder extends WithSymbols<
+    {
+      readonly [I in keyof typeof Items]: number;
+    } & {
+      readonly totalItems: number;
+      readonly firstItem?: ItemSymbol;
+      readonly itemCapacity: number;
+    }
+  > {}
 
-declare global {
-  interface LiquidHolder
-    extends WithSymbols<
-      {
-        readonly [L in keyof typeof Liquids]: number;
-      } & {
-        readonly totalLiquids: number;
-        readonly liquidCapacity: number;
-      }
-    > {}
-
-  interface ItemHolder
-    extends WithSymbols<
-      {
-        readonly [I in keyof typeof Items]: number;
-      } & {
-        readonly totalItems: number;
-        readonly firstItem?: ItemSymbol;
-        readonly itemCapacity: number;
-      }
-    > {}
-
-  interface PowerHolder
-    extends WithSymbols<{
-      readonly totalPower: number;
-      readonly powerCapacity: number;
-      readonly powerNetStored: number;
-      readonly powerNetCapacity: number;
-      readonly powerNetIn: number;
-      readonly powerNetOut: number;
-    }> {}
+  interface PowerHolder extends WithSymbols<{
+    /** The amount of power stored in this building. */
+    readonly totalPower: number;
+    /** The maximum amount of power this building can hold. */
+    readonly powerCapacity: number;
+    /**
+     * The amount of power stored in the power net that is this building is a
+     * part of.
+     */
+    readonly powerNetStored: number;
+    /**
+     * The maximum amount of power that can be stored in the power net that is
+     * this building is a part of.
+     */
+    readonly powerNetCapacity: number;
+    /**
+     * How much power is being generated in the power net that is this building
+     * is a part of.
+     */
+    readonly powerNetIn: number;
+    /**
+     * How much power is being spent in the power net that is this building is a
+     * part of.
+     */
+    readonly powerNetOut: number;
+  }> {}
+
+  interface WithAim extends WithSymbols<{
+    readonly shootX: number;
+    readonly shootY: number;
+  }> {}
 
   interface Shooting
-    extends WithSymbols<{
-      readonly shooting: boolean;
-      readonly shootX: number;
-      readonly shootY: number;
-      readonly ammo: number;
-      readonly ammoCapacity: number;
-    }> {}
-
-  interface WithHealth
-    extends WithSymbols<{
-      readonly health: number;
-      readonly maxHealth: number;
-      readonly dead: boolean;
-    }> {}
-
-  interface Heatable
-    extends WithSymbols<{
-      readonly heat: number;
-    }> {}
-
-  interface WithEffiency
-    extends WithSymbols<{
-      readonly efficiency: number;
-    }> {}
-
-  interface WithProgress
-    extends WithSymbols<{
-      readonly progress: number;
-    }> {}
-
-  interface WithTimescale
-    extends WithSymbols<{
-      readonly timescale: number;
-    }> {}
-
-  interface Rotatable
-    extends WithSymbols<{
-      readonly rotation: number;
-    }> {}
-
-  interface Spaced
-    extends WithSymbols<{
-      readonly x: number;
-      readonly y: number;
-      readonly size: number;
-    }> {}
-
-  interface Ranged
-    extends WithSymbols<{
-      readonly range: number;
-    }> {}
-
-  interface Boosted
-    extends WithSymbols<{
-      readonly boosting: boolean;
-    }> {}
-
-  interface Mining
-    extends WithSymbols<{
-      readonly mineX: number;
-      readonly mineY: number;
-      readonly mining: number;
-    }> {}
-
-  interface Typed<T extends symbol = symbol>
-    extends WithSymbols<{
-      readonly type: T;
-    }> {}
-  interface Flagged
-    extends WithSymbols<{
-      readonly flag: number;
-    }> {}
-
-  interface Controllable
-    extends WithSymbols<{
-      readonly controlled: 0 | ControlKind;
-      readonly controller: AnyUnit | BasicBuilding;
-    }> {}
-
-  interface Nameable
-    extends WithSymbols<{
-      readonly name?: string;
-    }> {}
-
-  interface PayloadHolder
-    extends WithSymbols<{
+    extends
+      WithAim,
+      WithSymbols<{
+        readonly shooting: boolean;
+        readonly ammo: number;
+        readonly ammoCapacity: number;
+        readonly currentAmmoType?: ItemSymbol | LiquidSymbol;
+      }> {}
+
+  interface WithHealth extends WithSymbols<{
+    readonly health: number;
+    readonly maxHealth: number;
+    readonly dead: boolean;
+  }> {}
+
+  interface Heatable extends WithSymbols<{
+    /**
+     * Can mean:
+     *
+     * - The damage buildup in the force field of force projectors. This buildup
+     *   decreases over time as the force projector regenerates.
+     * - The warmup progress of impact reactors, in the range: [0, 1].
+     * - The heat of a thorium reactor, in the range: [0, 1].
+     */
+    readonly heat: number;
+  }> {}
+
+  interface WithShield extends WithSymbols<{
+    /**
+     * The amount of shield hp `this` has.
+     *
+     * If `this` has a force field, returns the force field's hp.
+     *
+     * Or else, if `this` is an unit, returns the hp of this unit's personal
+     * shield, which is as one given by a `pulsar`.
+     */
+    readonly shield: number;
+  }> {}
+
+  interface WithEffiency extends WithSymbols<{
+    readonly efficiency: number;
+  }> {}
+
+  interface WithProgress extends WithSymbols<{
+    /**
+     * Action progress, in the range: [0, 1].
+     *
+     * Returns the production, turret reload or construction progress.
+     */
+    readonly progress: number;
+  }> {}
+
+  interface WithTimescale extends WithSymbols<{
+    /**
+     * The speed boost applied to this building by, for example, an overdrive
+     * projector.
+     */
+    readonly timescale: number;
+  }> {}
+
+  interface Rotatable extends WithSymbols<{
+    /**
+     * The rotation of this entity.
+     *
+     * Most buildings have their rotation represented by an integer within the
+     * range [0, 3]. With each meaning:
+     *
+     * - 0 => right
+     * - 1 => up
+     * - 2 => left
+     * - 3 => down
+     *
+     * While units and some other buildings (like turrets) will have their
+     * rotation represented in degrees stored in a floating point number.
+     */
+    readonly rotation: number;
+  }> {}
+
+  interface Spaced extends WithSymbols<{
+    readonly x: number;
+    readonly y: number;
+    readonly size: number;
+  }> {}
+
+  interface Ranged extends WithSymbols<{
+    readonly range: number;
+  }> {}
+
+  interface Boosted extends WithSymbols<{
+    readonly boosting: boolean;
+  }> {}
+
+  interface Mining extends WithSymbols<{
+    readonly mineX: number;
+    readonly mineY: number;
+    readonly mining: number;
+  }> {}
+
+  interface Typed<T extends symbol = symbol> extends WithSymbols<{
+    readonly type: T;
+  }> {}
+  interface Flagged extends WithSymbols<{
+    readonly flag: number;
+  }> {}
+
+  interface Controlled extends WithSymbols<{
+    /**
+     * The type of control that is being applied to `this`.
+     *
+     * If `this` is a building:
+     *
+     * - `ControlKind.ctrlPlayer` if a player is controlling `this`.
+     * - `0` otherwise.
+     *
+     * If `this` is an unit:
+     *
+     * - `ControlKind.ctrlProcessor` if `this` is being controlled by a processor.
+     * - `ControlKind.ctrlPlayer` if `this` is being controlled directly by a
+     *   player.
+     * - `ControlKind.ctrlCommand` if `this` is being controlled by player
+     *   commands.
+     * - `0` otherwise.
+     */
+    readonly controlled: 0 | ControlKind;
+  }> {}
+
+  interface WithController extends WithSymbols<{
+    /**
+     * The entity controlling this unit. Is either a player, a processor or
+     * `this`.
+     */
+    readonly controller: AnyUnit | BasicBuilding;
+  }> {}
+
+  interface Nameable extends WithSymbols<{
+    /** The name of the player controlling this unit. */
+    readonly name?: string;
+  }> {}
+
+  interface PayloadHolder extends WithSymbols<
+    {
+      readonly [T in UnitSymbol | BlockSymbol]: number;
+    } & {
       readonly payloadCount: number;
-      readonly payloadType?: symbol;
-    }> {}
+      readonly payloadType?: UnitSymbol | BlockSymbol;
+      readonly totalPayload: number;
+      readonly payloadCapacity: number;
+    }
+  > {}
 
-  interface WithEnable
-    extends WithSymbols<{
-      enabled: boolean;
-    }> {}
+  interface WithEnable extends WithSymbols<{
+    readonly enabled: boolean;
+  }> {}
   interface WithConfig<
-    T extends symbol | number | undefined = symbol | undefined
+    T extends symbol | number | undefined = symbol | undefined,
   > extends WithSymbols<{
-      readonly config: T;
-    }> {}
-
-  interface WithSpeed
-    extends WithSymbols<{
-      speed: number;
-    }> {}
-
-  interface WithColor
-    extends WithSymbols<{
-      color: number;
-    }> {}
-
-  interface WithTeam
-    extends WithSymbols<{
-      team: number;
-    }> {}
+    readonly config: T;
+  }> {}
+
+  interface WithSpeed extends WithSymbols<{
+    /** The base movement speed of this unit. Measured in tiles/second. */
+    readonly speed: number;
+  }> {}
+
+  interface WithColor extends WithSymbols<{
+    /**
+     * Can be:
+     *
+     * - Color of the `this`, if it is an illuminator.
+     * - Color of the team of `this`.
+     */
+    readonly color: number;
+  }> {}
+
+  interface WithTeam extends WithSymbols<{
+    /** The team id of `this`. */
+    readonly team: number;
+  }> {}
+
+  interface WithArmor extends WithSymbols<{
+    readonly armor: number;
+  }> {}
+
+  interface WithCamera extends WithSymbols<{
+    /**
+     * The player camera X coordinate. Privileged (world) processors only;
+     * evaluates to null on standard processors.
+     */
+    readonly cameraX: number;
+    /**
+     * The player camera Y coordinate. Privileged (world) processors only;
+     * evaluates to null on standard processors.
+     */
+    readonly cameraY: number;
+    /**
+     * The player camera viewport width. Privileged (world) processors only;
+     * evaluates to null on standard processors.
+     */
+    readonly cameraWidth: number;
+    /**
+     * The player camera viewport height. Privileged (world) processors only;
+     * evaluates to null on standard processors.
+     */
+    readonly cameraHeight: number;
+  }> {}
+
+  interface WithDisplay extends WithSymbols<{
+    readonly displayHeight: number;
+    readonly displayWidth: number;
+  }> {}
+
+  interface WithMemory extends WithSymbols<{
+    readonly memoryCapacity: number;
+  }> {}
+
+  interface WithBufferSize extends WithSymbols<{
+    readonly bufferSize: number;
+  }> {}
+
+  interface WithSolid extends WithSymbols<{
+    readonly solid: boolean;
+  }> {}
+
+  interface WithVelocity extends WithSymbols<{
+    readonly velocityX: number;
+    readonly velocityY: number;
+  }> {}
+
+  interface WithOperations extends WithSymbols<{
+    readonly operations: number;
+  }> {}
+
+  interface WithPing extends WithSymbols<{
+    readonly pingX: number;
+    readonly pingY: number;
+    readonly pingText?: string;
+  }> {}
+
+  interface WithSelected extends WithSymbols<{
+    readonly selectedBlock?: BlockSymbol;
+    readonly selectedRotation: number;
+  }> {}
+
+  interface WithBulletTime extends WithSymbols<{
+    readonly bulletLifetime: number;
+    readonly bulletTime: number;
+  }> {}
+
+  interface WithBuild extends WithSymbols<{
+    readonly buildX: number;
+    readonly buildY: number;
+    readonly building?: BasicBuilding;
+    readonly breaking?: BasicBuilding;
+  }> {}
+
+  interface Flying extends WithSymbols<{
+    readonly flying: boolean;
+  }> {}
+
+  interface WithMaxUnits extends WithSymbols<{
+    readonly maxUnits?: number;
+  }> {}
 }