reforged-types 1.0.0-alpha.0

package/3.0.0.d.ts

@@ -0,0 +1,9 @@
+/** @noSelfInFile */
+// Generated by reforged-types: the entry of game version 3.0.0, Patch 3.0.0.24268.
+// Source: jass-history tag Reforged-v3.0.0.24268-w3-3a9d8f2, commit a392fc3d5e6c37980accbfc560b28387fc7d01bc.
+// Do not edit: curate the Overlay, then run `pnpm --filter reforged-types typings:generate`.
+// common.ai is not referenced here: add `reforged-types/3.0.0/common.ai` to `types` to use it.
+/// <reference types="lua-types/5.3" resolution-mode="require" />
+/// <reference path="./lua-runtime.d.ts" />
+/// <reference path="./3.0.0/common.j.d.ts" />
+/// <reference path="./3.0.0/blizzard.j.d.ts" />

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2019 trigger
+Copyright (c) 2026 Paulo H. A. Leite
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# reforged-types
+
+TypeScript declarations for the Natives of Warcraft III Reforged, generated from the game's own Patch files, for map scripts compiled to Lua with [typescript-to-lua](https://typescripttolua.github.io/).
+
+**Supported Patch: 3.0.0.24268** (Game version 3.0.0). The `reforged.patch` field of `package.json` carries the same Build.
+
+<!-- The release's version step (release:version) stamps the docs version of each release into these links: docs/release.md. -->
+
+**For AI agents:** the documentation of this version as Markdown: [llms.txt](https://phmilk.github.io/reforged-ts/docs/next/llms.txt) links each page, and [llms-full.txt](https://phmilk.github.io/reforged-ts/docs/next/llms-full.txt) holds them all in one file.
+
+**Build phase.** Until 1.0.0, every version is an alpha (`1.0.0-alpha.N`) published under the `next` dist-tag. Install with `@next`: `pnpm add -D reforged-types@next`. npm gave `latest` to the first alpha, so `latest` stays on `1.0.0-alpha.0` until 1.0.0 is published, and moves to 1.0.0 then.
+
+## Usage
+
+```sh
+npm install --save-dev reforged-types@next
+```
+
+Add the entry of your Game version to `types` in `tsconfig.json`, next to the typescript-to-lua language extensions:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["@typescript-to-lua/language-extensions", "reforged-types/3.0.0"]
+  }
+}
+```
+
+That one line declares every `common.j` Native, type and global, the `Blizzard.j` functions and globals, the Lua runtime globals the game adds (`FourCC`, `__jarray`) and the Lua 5.3 standard library (through `lua-types`, a dependency of this package).
+
+The AI Natives of `common.ai` are valid only in AI scripts, so the entry leaves them out. To opt in, add their file as well:
+
+```json
+"types": ["@typescript-to-lua/language-extensions", "reforged-types/3.0.0", "reforged-types/3.0.0/common.ai"]
+```
+
+What the declarations give you:
+
+- Handle types are branded interfaces that mirror the Patch hierarchy (`framehandle extends agent`), so a `timer` passed where a `unit` is expected is a compile error.
+- A Native that can return nothing returns `T | undefined`; one the game guarantees returns `T`.
+- Callbacks are typed with `this: void` and every file is `@noSelfInFile`, so typescript-to-lua emits plain Lua functions.
+- Jass arrays (`bj_*` array globals) are `Record<number, T>`, indexed from 0 as in Jass.
+- Each Native's hover shows its Jass types (`integer (32-bit)`, `real`), `@async` when its value is valid only for the local player, `@deprecated` with the reason, `@patch` for the Patch that added it, and a link to its reference page.
+
+`async-natives.json` lists the Natives marked `@async`, for lint rules that read the same facts.
+
+## The Overlay
+
+The Patch files give names, parameters and types, but not whether a Native can return nothing, which Natives are async, or what is deprecated. The Overlay holds those facts: one hand-curated JSON file per Native and global (nullability of the return and of each parameter, async, deprecation, notes, the Patch that added it), kept in the [repository](https://github.com/phmilk/reforged-ts/tree/master/packages/reforged-types/overlay). The generator merges it with the Patch files and fails on any declaration without an entry, so every nullable type in these Typings is a reviewed decision. To correct one, change that Native's Overlay file in a pull request.
+
+## Attribution
+
+The Overlay was seeded with the nullability decisions of [war3-types-strict](https://github.com/TinkerWorX/war3-types-strict), used under its MIT license:
+
+```text
+MIT License
+
+Copyright (c) 2021 Nikolaj Mariager
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+The Patch files are taken from [jass-history](https://github.com/Luashine/jass-history); the provenance file of each vendored Patch records the tag, commit and sha256 of every file.
+
+## Legal position
+
+The Typings are derived from Blizzard's Patch files, which the repository vendors as every community mirror does: Blizzard's EULA grants no right to redistribute them, and no enforcement against such mirrors has been found.
+
+## Regenerating
+
+From a clone of the repository, `pnpm --filter reforged-types typings:generate <jass-history tag>` vendors a Patch and regenerates; without a tag it regenerates from the vendored Patch files. The loop for a new Patch is in [`AGENTS.md`](https://github.com/phmilk/reforged-ts/blob/master/packages/reforged-types/AGENTS.md).
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/async-natives.json

@@ -0,0 +1,69 @@
+[
+  "BlzCameraGetCameraType",
+  "BlzFrameGetAlpha",
+  "BlzFrameGetChild",
+  "BlzFrameGetChildrenCount",
+  "BlzFrameGetEnable",
+  "BlzFrameGetHeight",
+  "BlzFrameGetParent",
+  "BlzFrameGetText",
+  "BlzFrameGetValue",
+  "BlzFrameGetWidth",
+  "BlzFrameIsVisible",
+  "BlzFrameToPixelX",
+  "BlzFrameToPixelY",
+  "BlzGetAbilityActivatedExtendedTooltip",
+  "BlzGetAbilityActivatedTooltip",
+  "BlzGetAbilityExtendedTooltip",
+  "BlzGetAbilityResearchExtendedTooltip",
+  "BlzGetAbilityResearchTooltip",
+  "BlzGetAbilityTooltip",
+  "BlzGetItemDescription",
+  "BlzGetItemExtendedTooltip",
+  "BlzGetItemTooltip",
+  "BlzGetLocalClientHeight",
+  "BlzGetLocalClientWidth",
+  "BlzGetLocalSpecialEffectX",
+  "BlzGetLocalSpecialEffectY",
+  "BlzGetLocalSpecialEffectZ",
+  "BlzGetLocalUnitZ",
+  "BlzGetLocale",
+  "BlzGetMouseFocusUnit",
+  "BlzGetMouseScreenPosX",
+  "BlzGetMouseScreenPosY",
+  "BlzGetUnitZ",
+  "BlzIsKeyPressed",
+  "BlzIsLocalClientActive",
+  "BlzIsMetaKeyPressed",
+  "BlzIsMouseButtonPressed",
+  "BlzPixelToFrameX",
+  "BlzPixelToFrameY",
+  "GetAllyColorFilterState",
+  "GetCameraBoundMaxX",
+  "GetCameraBoundMaxY",
+  "GetCameraBoundMinX",
+  "GetCameraBoundMinY",
+  "GetCameraEyePositionLoc",
+  "GetCameraEyePositionX",
+  "GetCameraEyePositionY",
+  "GetCameraEyePositionZ",
+  "GetCameraField",
+  "GetCameraFieldControlledByInput",
+  "GetCameraTargetPositionLoc",
+  "GetCameraTargetPositionX",
+  "GetCameraTargetPositionY",
+  "GetCameraTargetPositionZ",
+  "GetCreepCampFilterState",
+  "GetDestructableName",
+  "GetItemName",
+  "GetLocalPlayer",
+  "GetLocalizedHotkey",
+  "GetLocalizedString",
+  "GetLocationZ",
+  "GetObjectName",
+  "GetSoundDuration",
+  "GetSoundFileDuration",
+  "GetSoundIsPlaying",
+  "GetUnitName",
+  "IsMultiboardMinimized"
+]

package/lua-runtime.d.ts

@@ -0,0 +1,21 @@
+/** @noSelfInFile */
+// Hand-written: the globals the Warcraft III Lua runtime defines besides the
+// Natives and the Lua 5.3 standard library, limited to what the probe map
+// confirmed (#9) and the library needs. TypeDefine is left out until its
+// signature is established.
+
+/**
+ * The integer id of a four-character rawcode, as the Natives take it.
+ *
+ * @param id - four-character rawcode, such as `"hfoo"`
+ * @returns integer (32-bit)
+ */
+declare function FourCC(id: string): number;
+
+/**
+ * A table whose missing keys read as `defaultValue`: the Lua form of a Jass
+ * array, as the World Editor emits it for GUI variables.
+ *
+ * @param defaultValue - the value of every index not yet written
+ */
+declare function __jarray<T>(defaultValue: T): Record<number, T>;

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "reforged-types",
+  "version": "1.0.0-alpha.0",
+  "description": "TypeScript declarations for the Warcraft III Reforged natives, generated from the game's Patch files.",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "warcraft",
+    "wc3",
+    "reforged",
+    "typescript-to-lua"
+  ],
+  "homepage": "https://phmilk.github.io/reforged-ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phmilk/reforged-ts.git",
+    "directory": "packages/reforged-types"
+  },
+  "bugs": {
+    "url": "https://github.com/phmilk/reforged-ts/issues"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "reforged": {
+    "patch": "3.0.0.24268"
+  },
+  "files": [
+    "/[0-9]*.d.ts",
+    "/[0-9]*/*.d.ts",
+    "/lua-runtime.d.ts",
+    "/async-natives.json",
+    "/LICENSE",
+    "/README.md"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "lua-types": "^2.14.1"
+  },
+  "devDependencies": {
+    "@typescript-to-lua/language-extensions": "^1.19.0",
+    "@types/node": "^24.0.0",
+    "typescript": "6.0.2",
+    "typescript-to-lua": "^1.37.1",
+    "vitest": "^5.0.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && pnpm run typings:typecheck && pnpm run scripts:typecheck",
+    "typecheck": "tsc -p tsconfig.json --noEmit && pnpm run typings:typecheck && pnpm run scripts:typecheck",
+    "typings:typecheck": "tsc -p tsconfig.typings.json",
+    "scripts:typecheck": "tsc -p tsconfig.scripts.json",
+    "test": "vitest run --root ../.. --project reforged-types && pnpm run typings:check",
+    "vendor": "node build/cli/vendor.js",
+    "verify": "node build/cli/verify.js",
+    "typings:generate": "tsc -p tsconfig.json && node build/cli/generate.js",
+    "typings:check": "tsc -p tsconfig.json && node build/cli/check.js",
+    "seed:war3-types-strict": "node --experimental-strip-types scripts/seed-from-war3-types-strict.ts"
+  }
+}