warcraft-3-w3ts-utils 0.1.1

package/src/utils/misc.ts

@@ -0,0 +1,179 @@
+import { Effect, MapPlayer, Timer, Unit } from "w3ts";
+
+type ProperColors = "goldenrod" | "magenta" | "green" | "yellow" | "red" | "player1-red" | "player2-blue" | "player3-teal" | "player4-purple" | "player5-yellow" | "player6-orange";
+
+export function tColor(text: string | number, color?: ProperColors | null, hex?: PlayerColorHex | string | null, alpha?: string) {
+    if (color) {
+        return `|cff${properColorHexes.get(color) || "FFFFFF"}${alpha || ""}${text}|r`;
+    } else if (hex) {
+        return `|cff${hex}${alpha || ""}${text}|r`;
+    }
+
+    return String(text);
+}
+
+/**
+ * Colorizes the string according to the map player
+ */
+export function ptColor(player: MapPlayer, text: string) {
+    return `${tColor(text, undefined, playerColors[player.id])}`;
+}
+
+const properColorHexes = new Map<ProperColors, string>([
+    ["goldenrod", "ffcc00"],
+    ["green", "00FF00"],
+    ["yellow", "FFFF00"],
+    ["red", "FF0000"],
+    ["magenta", "FF00FF"],
+    ["player1-red", "ff0303"],
+    ["player2-blue", "0042ff"],
+    ["player3-teal", "1ce6b9"],
+    ["player4-purple", "540081"],
+    ["player5-yellow", "fffc00"],
+    ["player6-orange", "fe8a0e"],
+]);
+// enum PlayerColors {
+//     Player1 = "ff0303", // Red
+//     Player2 = "0042ff", // Blue
+//     Player3 = "1be7ba", // Teal
+//     Player4 = "550081", // Purple
+//     Player5 = "fefc00", // Yellow
+//     Player6 = "fe890d", // Orange
+//     Player7 = "21bf00", // Green
+//     Player8 = "e45caf", // Pink
+//     Player9 = "939596", // Gray
+//     Player10 = "7ebff1", // Light Blue
+//     Player11 = "106247", // Dark Green
+//     Player12 = "4f2b05", // Brown
+//     Player13 = "9c0000", // Maroon
+//     Player14 = "0000c3", // Navy
+//     Player15 = "00ebff", // Turquoise
+//     Player16 = "bd00ff", // Violet
+//     Player17 = "ecce87", // Wheat
+//     Player18 = "f7a58b", // Peach
+//     Player19 = "bfff81", // Mint
+//     Player20 = "dbb8eb", // Lavender
+//     Player21 = "4f5055", // Coal
+//     Player22 = "ecf0ff", // Snow
+//     Player23 = "00781e", // Emerald
+//     Player24 = "a56f34", // Peanut
+//     PlayerNeutral = "2e2d2e", // Black
+// }
+
+export enum PlayerColorHex {
+    Red = "ff0303",
+    Blue = "0042ff",
+    Teal = "1be7ba",
+    Purple = "550081",
+    Yellow = "fefc00",
+    Orange = "fe890d",
+    Green = "21bf00",
+    Pink = "e45caf",
+    Gray = "939596",
+    LightBlue = "7ebff1",
+    DarkGreen = "106247",
+    Brown = "4f2b05",
+    Maroon = "9c0000",
+    Navy = "0000c3",
+    Turquoise = "00ebff",
+    Violet = "bd00ff",
+    Wheat = "ecce87",
+    Peach = "f7a58b",
+    Mint = "bfff81",
+    Lavender = "dbb8eb",
+    Coal = "4f5055",
+    Snow = "ecf0ff",
+    Emerald = "00781e",
+    Peanut = "a56f34",
+    Black = "2e2d2e",
+}
+
+const playerColors = [
+    "ff0303", // Player 1: Red
+    "0042ff", // Player 2: Blue
+    "1be7ba", // Player 3: Teal
+    "550081", // Player 4: Purple
+    "fefc00", // Player 5: Yellow
+    "fe890d", // Player 6: Orange
+    "21bf00", // Player 7: Green
+    "e45caf", // Player 8: Pink
+    "939596", // Player 9: Gray
+    "7ebff1", // Player 10: Light Blue
+    "106247", // Player 11: Dark Green
+    "4f2b05", // Player 12: Brown
+    "9c0000", // Player 13: Maroon
+    "0000c3", // Player 14: Navy
+    "00ebff", // Player 15: Turquoise
+    "bd00ff", // Player 16: Violet
+    "ecce87", // Player 17: Wheat
+    "f7a58b", // Player 18: Peach
+    "bfff81", // Player 19: Mint
+    "dbb8eb", // Player 20: Lavender
+    "4f5055", // Player 21: Coal
+    "ecf0ff", // Player 22: Snow
+    "00781e", // Player 23: Emerald
+    "a56f34", // Player 24: Peanut
+    "2e2d2e", // Player Neutral: Black
+];
+
+/**
+ * Standardized format for notifying player of events.
+ */
+export function notifyPlayer(msg: string) {
+    print(`${tColor("!", "goldenrod")} - ${msg}`);
+}
+
+export function displayError(msg: string) {
+    print(`[ ${tColor("WARNING", "red")} ]: ${msg}`);
+}
+
+/**
+ * Returns degrees or radians?
+ */
+export function getRelativeAngleToUnit(unit: Unit, relativeUnit: Unit) {
+    const locA = GetUnitLoc(unit.handle);
+    const locB = GetUnitLoc(relativeUnit.handle);
+    const angle = AngleBetweenPoints(locA, locB);
+
+    RemoveLocation(locA);
+    RemoveLocation(locB);
+
+    return angle;
+}
+
+/**
+ * Manages state of effects in this context so you don't have to!
+ */
+export function useEffects() {
+    const effects: Effect[] = [];
+
+    return {
+        addEffect: (effect: Effect | undefined) => {
+            if (effect) {
+                effects.push(effect);
+            }
+        },
+        /**
+         * @returns reference to effects array
+         */
+        getEffects: () => {
+            return effects;
+        },
+        destroyAllEffects: () => {
+            effects.forEach((e) => {
+                e.destroy();
+            });
+        },
+    };
+}
+
+export function useTempEffect(effect: Effect | undefined, duration: number = 1.5) {
+    if (effect) {
+        const timer = Timer.create();
+
+        timer.start(duration, false, () => {
+            effect.destroy();
+            timer.destroy();
+        });
+    }
+}

package/src/utils/physics.ts

@@ -0,0 +1,295 @@
+// import { WTS_Units } from "src/enums/WTS_Enums";
+// import { PlayerIndex } from "src/player/player-data";
+import { Effect, Timer, Unit } from "w3ts";
+import { OrderId, Players } from "w3ts/globals";
+
+interface ApplyForceConfig {
+  /**
+   * Default: 0
+   */
+  sustainedForceDuration?: number;
+  /**
+   * Default: -2400 units per second
+   */
+  frictionConstant?: number;
+  /**
+   * The unit will not phase through unpathable areas
+   */
+  obeyPathing?: boolean;
+  whileActive?: (currentSpeed?: number, timeElapsed?: number) => void;
+  onStart?: (currentSpeed?: number, timeElapsed?: number) => void;
+  onEnd?: (currentSpeed?: number, timeElapsed?: number) => void;
+  /**
+   *
+   */
+  targetSpeed?: number;
+  /**
+   * In seconds
+   */
+  accelerationTime?: number;
+  /**
+   * This will be used to decide if the unit the force is applied on is allowed to deviate from their current path.
+   */
+  strictPathing?: boolean;
+  animationIndexNumber?: number;
+  dummyUnitPlayerIndex: number;
+  dummyUnitFourCC: number;
+}
+
+/**
+ * @param angle degrees
+ * @param unit
+ * @param initialSpeed meters per second
+ * @param affectHeight determines whether or not to change unit height whilst force is applied
+ */
+export function applyForce(
+  angle: number,
+  unit: Unit,
+  initialSpeed: number,
+  config: ApplyForceConfig
+) {
+  const timer = Timer.create();
+  const refreshInterval = 0.01;
+  const updatesPerSecond = 1 / refreshInterval;
+  const frictionConstant = 4800; //meters per second friction decay
+  let currentSpeed = initialSpeed;
+  let timeElapsed = 0;
+
+  const clickMoveOrder = 851971;
+  const moveOrders = [
+    OrderId.Move,
+    OrderId.Attackground,
+    OrderId.Patrol,
+    OrderId.Attack,
+    clickMoveOrder,
+  ];
+
+  let forceDummyUnit: Unit | undefined = undefined;
+  const defaultX = 11800;
+  const defaultY = -5700;
+
+  //Cancel unit commands - if a unit already has a move command and are applied a force, they will bug out sometimes and walk in the opposite direction
+  // unit.issueImmediateOrder(OrderId.Stop);
+
+  /**
+   * Prematurely end the force effect
+   */
+  function destroyForceEffect(runOnEnd: boolean = false) {
+    if (runOnEnd && config?.onEnd) {
+      config.onEnd();
+    }
+
+    ResetUnitAnimation(unit.handle);
+    forceDummyUnit?.destroy();
+    timer.destroy();
+  }
+
+  /**
+   * These are the positions the unit would be if there were no minor disturbances
+   */
+  let theoreticalX = unit.x;
+  let theoreticalY = unit.y;
+
+  /**
+   * The distance the true unit position can be from the theoretical position. Helps stop sliding against walls, etc.
+   */
+  // const BREAK_DISTANCE = 100;
+
+  if (!forceDummyUnit) {
+    forceDummyUnit = Unit.create(
+      Players[config.dummyUnitPlayerIndex],
+      config.dummyUnitPlayerIndex,
+      defaultX,
+      defaultY
+    );
+  }
+
+  // unit.issueImmediateOrder(OrderId.Stop);
+
+  if (config?.animationIndexNumber) {
+    ResetUnitAnimation(unit.handle);
+    SetUnitAnimationByIndex(unit.handle, config.animationIndexNumber);
+  }
+
+  timer.start(refreshInterval, true, () => {
+    //If for whatever reason the unit no longer exists.
+    if (!unit) {
+      destroyForceEffect();
+      return destroyForceEffect;
+    }
+
+    // if (distanceBetweenPoints(unit.x, unit.y, theoreticalX, theoreticalY) > BREAK_DISTANCE) {
+    //     print("unit was to far away from theoretical distance");
+    //     const e = Effect.create("Abilities\\Spells\\Other\\TalkToMe\\TalkToMe", theoreticalX, theoreticalY);
+    //     e?.setScaleMatrix(2, 2, 2);
+    //     unit.issueImmediateOrder(OrderId.Stop);
+
+    //     destroyForceEffect(true);
+    //     return;
+    // }
+
+    //if the unit's move speed vector is greater than the remaining applied force vector then we may stop the applied force function; should only run while the unit has the move order
+    // if (config?.obeyPathing && !config.strictPathing && currentSpeed > unit.moveSpeed) {
+    //     unit.issueImmediateOrder(OrderId.Stop);
+    // }
+
+    //should probably only do strict pathing so nothing else interfers with the unit moving
+    if (forceDummyUnit && config?.strictPathing) {
+      const isWindWalked = UnitHasBuffBJ(forceDummyUnit.handle, FourCC("BOwk"));
+
+      if (!isWindWalked) {
+        forceDummyUnit.issueImmediateOrder(OrderId.Windwalk);
+      }
+      // forceDummyUnit.issueImmediateOrder(OrderId.Stop);
+
+      //Move dummy to the position we want the unit to be in
+      forceDummyUnit.x = unit.x;
+      forceDummyUnit.y = unit.y;
+
+      forceDummyUnit.issueImmediateOrder(OrderId.Stop);
+
+      //flooring values since it can be off sometimes by a thousandth
+      if (
+        Math.floor(forceDummyUnit.x) !== Math.floor(unit.x) ||
+        Math.floor(forceDummyUnit.y) !== Math.floor(unit.y)
+      ) {
+        // print(`Collision detected! Dummy x: ${forceDummyUnit.x} y: ${forceDummyUnit.y} Unit x: ${unit.x} y: ${unit.y}`);
+        const e = Effect.create(
+          "Abilities\\Spells\\Other\\TalkToMe\\TalkToMe",
+          forceDummyUnit.x,
+          forceDummyUnit.y
+        );
+        e?.setScaleMatrix(2, 2, 2);
+        destroyForceEffect(true);
+        return;
+      }
+    }
+
+    const xVelocity =
+      (currentSpeed / updatesPerSecond) * Math.cos(Deg2Rad(angle));
+    const yVelocity =
+      (currentSpeed / updatesPerSecond) * Math.sin(Deg2Rad(angle));
+
+    //Complete execution when current speed of the initial force has decayed
+    if (currentSpeed <= 0) {
+      destroyForceEffect(true);
+      return;
+    }
+
+    //Runs when the force is first applied
+    if (config?.onStart && currentSpeed === initialSpeed) {
+      config.onStart(currentSpeed, timeElapsed);
+    }
+
+    //Runs at any point while the function is executing
+    if (config?.whileActive) {
+      config.whileActive(currentSpeed, timeElapsed);
+    }
+
+    theoreticalX += xVelocity;
+    theoreticalY += yVelocity;
+
+    //basically the same thing now since we are no longer issuing the stop command on the unit.
+    //also the moment another force is applied to the unit the previous force will stop being applied.
+    if (config?.strictPathing) {
+      unit.x = theoreticalX;
+      unit.y = theoreticalY;
+    } else {
+      unit.x += xVelocity;
+      unit.y += yVelocity;
+    }
+
+    timeElapsed += refreshInterval;
+
+    if (
+      config?.sustainedForceDuration &&
+      timeElapsed <= config.sustainedForceDuration
+    ) {
+      return;
+    }
+
+    currentSpeed -= frictionConstant / updatesPerSecond;
+  });
+
+  return { destroyForceEffect };
+}
+
+/**
+ * @param angle degrees
+ * @param effect
+ * @param initialSpeed meters per second
+ * @param affectHeight determines whether or not to change unit height whilst force is applied
+ */
+export function applyForceForEffect(
+  angle: number,
+  effect: Effect,
+  initialSpeed: number,
+  config?: ApplyForceConfig
+) {
+  const timer = Timer.create();
+  const refreshInterval = 0.01;
+  const updatesPerSecond = 1 / refreshInterval;
+  const frictionConstant = 1200; //meters per second friction decay
+  let currentSpeed = initialSpeed;
+  let timeElapsed = 0;
+
+  //Cancel unit commands - if a unit already has a move command and are applied a force, they will bug out sometimes and walk in the opposite direction
+
+  timer.start(refreshInterval, true, () => {
+    //if the unit's move speed vector is greater than the remaining applied force vector then we may stop the applied force function; should only run while the unit has the move order
+    const xVelocity =
+      (currentSpeed / updatesPerSecond) * Math.cos(Deg2Rad(angle));
+    const yVelocity =
+      (currentSpeed / updatesPerSecond) * Math.sin(Deg2Rad(angle));
+
+    //On end hook runs before the timer is destroyed and the function ends
+    if (config?.onEnd && currentSpeed <= 0) {
+      config.onEnd(currentSpeed, timeElapsed);
+    }
+
+    //Complete execution when current speed of the initial force has decayed
+    if (currentSpeed <= 0) {
+      timer.destroy();
+      return;
+    }
+
+    //Runs when the force is first applied
+    if (config?.onStart && currentSpeed === initialSpeed) {
+      config.onStart(currentSpeed, timeElapsed);
+    }
+
+    //Runs at any point while the function is executing
+    if (config?.whileActive) {
+      config.whileActive(currentSpeed, timeElapsed);
+    }
+
+    effect.x += xVelocity;
+    effect.y += yVelocity;
+
+    timeElapsed += refreshInterval;
+
+    if (
+      config?.sustainedForceDuration &&
+      timeElapsed <= config.sustainedForceDuration
+    ) {
+      return;
+    }
+
+    currentSpeed -= frictionConstant / updatesPerSecond;
+  });
+
+  function destroyForceEffect() {
+    timer.destroy();
+  }
+
+  return { destroyForceEffect };
+}
+
+// const unitIsMovingVector_x = (unit.moveSpeed / updatesPerSecond) * Math.cos(Deg2Rad(unit.facing));
+// const unitIsMovingVector_y = (unit.moveSpeed / updatesPerSecond) * Math.sin(Deg2Rad(unit.facing));
+// if ((moveOrders.includes(unit.currentOrder) && unitIsMovingVector_x > xVelocity) || unitIsMovingVector_y > yVelocity) {
+//     print("moving velocity exceeded applied force velocity");
+//     timer.destroy();
+
+//     return;
+// }

package/src/utils/players.ts

@@ -0,0 +1,214 @@
+import { Group, MapPlayer, Rectangle, Trigger, Unit } from "w3ts";
+import { Players } from "w3ts/globals";
+
+/**
+ * Does a callback for every unit of the player that has the ability
+ * @param player
+ * @param abilityId
+ * @param cb
+ */
+export function forEachUnitOfPlayerWithAbility(player: MapPlayer, abilityId: number, cb: (unit: Unit) => void) {
+    forEachUnitOfPlayer(player, (u) => {
+        for (let x = 0; x < 12; x++) {
+            const currentAbility = u.getAbilityByIndex(x);
+
+            if (currentAbility && currentAbility === u.getAbility(abilityId) && u.isAlive()) {
+                cb(u);
+            }
+        }
+    });
+}
+
+/**
+ * Calls a function for each player playing and is an ally of red.
+ * @warning specific to map
+ */
+export function forEachAlliedPlayer(cb: (player: MapPlayer, index: number) => void) {
+    Players.forEach((player, index) => {
+        //For testing purposes, include player[9] (the human ally) so their units can also be included when iterating the units OR i should make a separate function for all units.
+        if (player.slotState === PLAYER_SLOT_STATE_PLAYING && player.isPlayerAlly(Players[0]) && player != Players[25] && player != Players[27]) {
+            cb(player, index);
+        }
+    });
+}
+
+export function forEachPlayer(cb: (player: MapPlayer, index: number) => void) {
+    Players.forEach((p, index) => {
+        cb(p, index);
+    });
+}
+
+/**
+ * Executes the callback function for each unit matching the unit type for the player
+ * @param unitType Unit Type Id or the Unit Type String "hcas", etc
+ */
+export function forEachUnitTypeOfPlayer(unitType: number | string, player: MapPlayer, cb: (unit: Unit) => void) {
+    if (typeof unitType === "string") {
+        unitType = FourCC(unitType);
+    }
+
+    const g = Group.create();
+
+    g?.enumUnitsOfPlayer(player, () => {
+        const unit = Group.getFilterUnit();
+
+        if (unit && unit?.typeId === unitType) {
+            cb(unit);
+        }
+
+        return true;
+    });
+
+    g?.destroy();
+}
+
+/**
+ * Doesn;'t appear to actually work?
+ * @broken
+ * @param unitName
+ * @param unitType
+ * @param fn
+ */
+export function forEachUnitOfType(unitName: string, unitType: number | string, fn: (unit: Unit) => void) {
+    if (typeof unitType === "string") {
+        unitType = FourCC(unitType);
+    }
+
+    print(unitName);
+
+    const g = Group.create();
+
+    g?.enumUnitsOfType(unitName, () => {
+        const unit = Group.getFilterUnit();
+
+        if (unit && unit?.typeId === unitType) {
+            fn(unit);
+        }
+
+        return true;
+    });
+
+    print(`Total units of name ${unitName} found: ${g?.size}`);
+
+    g?.destroy();
+}
+
+/**
+ * @param unitType Unit Type Id or the Unit Type String "hcas", etc
+ */
+export function forEachUnitOfPlayer(player: MapPlayer, cb: (unit: Unit) => void) {
+    const g = Group.create();
+
+    g?.enumUnitsOfPlayer(player, () => {
+        const unit = Group.getFilterUnit();
+
+        if (!unit) {
+            print("Enumerating over a unit that doesn't exist!");
+        }
+        if (unit) {
+            cb(unit);
+        }
+
+        return true;
+    });
+
+    g?.destroy();
+}
+
+/**
+ * Executes the callback function for each unit matching the unit type for the player
+ * @param unitType Unit Type Id or the Unit Type String "hcas", etc
+ */
+export function forEachUnitInRectangle(rectangle: Rectangle, cb: (unit: Unit) => void) {
+    const g = Group.create();
+
+    g?.enumUnitsInRect(rectangle, () => {
+        const unit = Group.getFilterUnit();
+
+        if (unit) {
+            cb(unit);
+        }
+
+        return true;
+    });
+
+    g?.destroy();
+}
+
+export function isPlaying(player: MapPlayer | player) {
+    if (player instanceof MapPlayer) {
+        return player.slotState === PLAYER_SLOT_STATE_PLAYING;
+    }
+
+    return GetPlayerSlotState(player) === PLAYER_SLOT_STATE_PLAYING;
+}
+
+export function isUser(player: MapPlayer | player) {
+    if (player instanceof MapPlayer) {
+        return GetPlayerController(player.handle) === MAP_CONTROL_USER;
+    }
+
+    return GetPlayerController(player) === MAP_CONTROL_USER;
+}
+
+export function isComputer(player: MapPlayer) {
+    if (player instanceof MapPlayer) {
+        return GetPlayerController(player.handle) === MAP_CONTROL_COMPUTER;
+    }
+
+    return GetPlayerController(player) === MAP_CONTROL_COMPUTER;
+}
+
+export function isPlayingUser(player: MapPlayer | player) {
+    return isUser(player) && isPlaying(player);
+}
+
+export function adjustPlayerState(player: MapPlayer, whichState: playerstate, amount: number) {
+    player.setState(whichState, player.getState(whichState) + amount);
+}
+
+export function adjustGold(player: MapPlayer, amount: number) {
+    player.setState(PLAYER_STATE_RESOURCE_GOLD, player.getState(PLAYER_STATE_RESOURCE_GOLD) + amount);
+}
+
+export function adjustLumber(player: MapPlayer, amount: number) {
+    player.setState(PLAYER_STATE_RESOURCE_LUMBER, player.getState(PLAYER_STATE_RESOURCE_LUMBER) + amount);
+}
+
+export function adjustFoodCap(player: MapPlayer, amount: number) {
+    player.setState(PLAYER_STATE_RESOURCE_FOOD_CAP, player.getState(PLAYER_STATE_RESOURCE_FOOD_CAP) + amount);
+}
+
+export function adjustFoodUsed(player: MapPlayer, amount: number) {
+    player.setState(PLAYER_STATE_RESOURCE_FOOD_USED, player.getState(PLAYER_STATE_RESOURCE_FOOD_USED) + amount);
+}
+
+export function playerHasResources(player: MapPlayer, data: { gold?: number; lumber?: number }) {
+    let hasGold = true;
+    let hasLumber = true;
+
+    if (data.gold && data.gold != 0) {
+        hasGold = player.getState(PLAYER_STATE_RESOURCE_GOLD) >= data.gold;
+    }
+
+    if (data.lumber && data.lumber != 0) {
+        hasLumber = player.getState(PLAYER_STATE_RESOURCE_LUMBER) >= data.lumber;
+    }
+
+    return hasGold && hasLumber;
+}
+
+export function setPlayerName() {
+    const t = Trigger.create();
+    forEachPlayer((p) => {
+        t.registerPlayerChatEvent(p, "-playername ", false);
+
+        t.addAction(() => {
+            const str = GetEventPlayerChatString();
+            const newName = str?.replace("-playername", "");
+            if (newName) {
+                SetPlayerName(p.handle, newName);
+            }
+        });
+    });
+}