wc3-map-ts-template: Instructions file for GitHub Copilot

Warcraft III TypeScript Map Development Template

Project Architecture

This is a Warcraft III 1.27a map development template using TypeScript-to-Lua compilation. The project integrates multiple specialized tools for WC3 modding:

• KKWE (Kunkka World Editor) - Enhanced world editor with JAPI extensions
• w3x2lni - Map format converter for LNI (Lua Nested Interface) editing
• typescript-to-lua (tstl) - Compiles TypeScript to Lua for WC3 execution
• @eiriksgata/wc3ts - TypeScript definitions for Warcraft III APIs

@eiriksgata/wc3ts Library Reference

When developing with this template, always reference the @eiriksgata/wc3ts library for:

Core API Structure

• handles/ - Wrapper classes for WC3 objects (Unit, Effect, Player, etc.)
• globals/ - Global constants, enums, and predefined values
• system/ - Utility systems (base64, binary readers/writers, file operations)
• utils/ - Helper utilities (color management, KKWE extensions)
• types/ - TypeScript type definitions for JASS functions

Documentation Patterns

Follow the library's documentation style:

• Use JSDoc comments with @param, @returns, @deprecated, @note tags
• Include detailed parameter descriptions
• Mark deprecated methods and suggest alternatives
• Use /** @noSelfInFile */ for files that shouldn't have implicit self

Naming Conventions

• Classes use PascalCase: Unit, Effect, MapPlayer
• Methods use camelCase: addAbility(), setColor()
• Constants use UPPER_SNAKE_CASE: UNIT_STATE_LIFE, PLAYER_COLOR_RED
• Handle properties are readonly: readonly handle: unit

Players 全局数组（重要！）

wc3ts 预定义了 Players 全局数组，可以直接通过索引获取玩家对象：

import { Players } from "@eiriksgata/wc3ts";

// Players[0] = 玩家1 (红色)
// Players[1] = 玩家2 (蓝色)
// Players[2] = 玩家3 (青色)
// ...
// Players[11] = 玩家12
// Players[PLAYER_NEUTRAL_AGGRESSIVE] = 中立敌对 (索引12)
// Players[PLAYER_NEUTRAL_PASSIVE] = 中立被动 (索引15)

// 直接使用 Players[n] 获取玩家，无需 MapPlayer.fromIndex()
const player1 = Players[0];  // 玩家1
const player2 = Players[1];  // 玩家2

// Unit.create 的第一个参数类型是 MapPlayer，直接用 Players[n] 即可
const unit = Unit.create(Players[0], FourCC("hfoo"), x, y, facing);

// 遍历所有玩家
for (let i = 0; i < bj_MAX_PLAYERS; i++) {
  const player = Players[i];
  print(`玩家${i + 1}: ${player.name}`);
}