### Build Project with Nix

Source: https://github.com/luashine/jassdoc/blob/master/Readme.md

Build the Jassdoc project using Nix flakes. Requires a working Nix/Nixos installation.

```bash
nix build github:lep/jassdoc
```

--------------------------------

### JASS: One-shot Timer Example

Source: https://context7.com/luashine/jassdoc/llms.txt

Demonstrates creating and starting a one-shot timer that executes a callback function once after a specified duration. Ensure timers are destroyed after use to prevent memory leaks.

```jass
function OnExpire takes nothing returns nothing
    local timer t = GetExpiredTimer()
    call DestroyTimer(t)
    // ... do work ...
endfunction

function StartMyTimer takes nothing returns nothing
    local timer t = CreateTimer()
    call TimerStart(t, 5.0, false, function OnExpire)
    // t will fire once after 5 game-seconds
endfunction
```

--------------------------------

### JASS: Map Configuration Setup

Source: https://context7.com/luashine/jassdoc/llms.txt

Sets up various map properties like name, description, player count, and start locations within the `config` function. These settings are applied before the game begins.

```jass
function config takes nothing returns nothing
    call SetMapName("My Map |cffff0000v1.0|r")
    call SetMapDescription("Welcome!\n\nFFA for 4 players.")
    call SetPlayers(4)
    call SetTeams(4)
    call SetGamePlacement(MAP_PLACEMENT_USE_MAP_SETTINGS)

    call DefineStartLocation(0, -512.0,  512.0)
    call DefineStartLocation(1,  512.0,  512.0)
    call DefineStartLocation(2,  512.0, -512.0)
    call DefineStartLocation(3, -512.0, -512.0)

    call SetPlayerStartLocation(Player(0), 0)
    call SetPlayerColor(Player(0), PLAYER_COLOR_RED)
    call SetPlayerController(Player(0), MAP_CONTROL_USER)
endfunction
```

--------------------------------

### Example SQLite Queries for Jass Documentation

Source: https://context7.com/luashine/jassdoc/llms.txt

Demonstrates how to query the Jass documentation database for annotations, parameter details, and parameter ordering/types.

```sql
-- Example queries:
-- All annotations for a function:
SELECT anname, value FROM annotations WHERE fnname = 'GroupEnumUnitsInRange' ORDER BY rowid;

-- Parameter documentation:
SELECT param, value FROM parameters WHERE fnname = 'TimerStart';

-- Parameter type and order:
SELECT param, anname, value FROM params_extra WHERE fnname = 'CreateUnit' ORDER BY value;
```

--------------------------------

### Lua example for GetObjectName

Source: https://context7.com/luashine/jassdoc/llms.txt

This is a Lua example demonstrating how to use the `GetObjectName` function.

```lua
-- GetObjectName( FourCC("hfoo") ) --> "Footman"
```

--------------------------------

### Map Configuration API

Source: https://context7.com/luashine/jassdoc/llms.txt

Functions used within the `config` function to set up the game lobby before the game starts.

```APIDOC
## Map Configuration API

Used inside the `config` function in `war3map.j` to set up the lobby before the game starts. Calling these outside `config` compiles and runs, but has no effect on the lobby or starting positions.

```jass
function config takes nothing returns nothing
    call SetMapName("My Map |cffff0000v1.0|r")
    call SetMapDescription("Welcome!\n\nFFA for 4 players.")
    call SetPlayers(4)
    call SetTeams(4)
    call SetGamePlacement(MAP_PLACEMENT_USE_MAP_SETTINGS)

    call DefineStartLocation(0, -512.0,  512.0)
    call DefineStartLocation(1,  512.0,  512.0)
    call DefineStartLocation(2,  512.0, -512.0)
    call DefineStartLocation(3, -512.0, -512.0)

    call SetPlayerStartLocation(Player(0), 0)
    call SetPlayerColor(Player(0), PLAYER_COLOR_RED)
    call SetPlayerController(Player(0), MAP_CONTROL_USER)
endfunction
```
```

--------------------------------

### Documenting a native function with jassdoc

Source: https://context7.com/luashine/jassdoc/llms.txt

This example shows how to document a native function using Javadoc-style comments. It includes a general description, notes, parameter documentation, and flags.

```jass
/**
Reveals a player's remaining buildings to a force. The black mask over the
buildings will be removed as if the territory had been discovered.

@note This function will not check whether the player has a town hall before revealing.

@param whichPlayer The player to reveal.

@param toWhichPlayers The players who will see whichPlayer's buildings.

@param flag If true, the buildings will be revealed. If false, the buildings
will not be revealed. Note that if you set it to false, it will not hide the
buildings with a black mask.
*/
native CripplePlayer takes player whichPlayer, force toWhichPlayers, boolean flag returns nothing
```

--------------------------------

### Documenting a constant native with jassdoc

Source: https://context7.com/luashine/jassdoc/llms.txt

This example demonstrates documenting a constant native function. It includes a general description, notes, purity, async behavior, bug warnings, and patch version.

```jass
/**
Returns localized value for field "name" for the given object type ID.

@note See: `UnitId2String`.

@pure

@async

@bug Do not use this in a global initialisation (on map init) as it crashes the game there.

@patch 1.13
*/
constant native GetObjectName takes integer objectId returns string
```

--------------------------------

### Simple Jass Annotation Example

Source: https://github.com/luashine/jassdoc/blob/master/Readme.md

Demonstrates a concise Jass annotation for a single-line note, highlighting the use of Markdown for bold text within the note.

```jass
/**
@note one line. This word will be in **bold**
*/
```

--------------------------------

### Lua: Periodic Timer Example

Source: https://context7.com/luashine/jassdoc/llms.txt

Shows how to create a periodic timer that fires repeatedly at a set interval. Note that DestroyTimer does not pause the timer, and PauseTimer clears the periodic flag.

```lua
-- Lua: periodic 0.1-second timer
local t = CreateTimer()
TimerStart(t, 0.1, true, function()
    -- runs every 100 ms
    local elapsed = TimerGetElapsed(t)   -- time since last reset
    local remain  = TimerGetRemaining(t) -- time until next expiry
end)

-- Bug note: DestroyTimer does NOT pause the timer; the callback may
-- still fire once after destruction with GetExpiredTimer() == nil.
-- Bug note: PauseTimer clears the periodic flag.
```

--------------------------------

### Automatically Extract luahelper.lua

Source: https://github.com/luashine/jassdoc/blob/master/extra-lua/README.md

Use this script to automatically extract the luahelper.lua file. Ensure you have a Lua interpreter installed and the Warcraft 3 executable path correctly set.

```bash
export w3exe="$(cygpath 'D:\\SteamLibrary\\Warcraft III\\_retail_\\x86_64\\Warcraft III.exe')"
lua "extract-luahelper.lua" --luahelper "$w3exe" --no-debug > output-luahelper.lua
```

--------------------------------

### Get Destructable Skin Rawcode (Lua)

Source: https://context7.com/luashine/jassdoc/llms.txt

Use `BlzGetDestructableSkin` to retrieve the rawcode of a destructable's current skin.

```lua
-- BlzGetDestructableSkin: returns current skin rawcode
local tree = CreateDestructable(FourCC("ATtr"), -256, 256, 180.0, 1.0, 0)
print(BlzGetDestructableSkin(tree))  --> 1096053874 == FourCC("ATtr")
```

--------------------------------

### Documenting a Jass Function with Annotations

Source: https://github.com/luashine/jassdoc/blob/master/Readme.md

Example of documenting a Jass function using Javadoc-style comments with various annotations like @note, @param, and @return. This format is used to provide detailed information about function behavior, parameters, and potential issues.

```jass
/**
Reveals a player's remaining buildings to a force. The black mask over the
buildings will be removed as if the territory had been discovered

@note This function will not check whether the player has a town hall before revealing.

@param whichPlayer The player to reveal.

@param toWhichPlayers The players who will see whichPlayer's buildings.

@param flag If true, the buildings will be revealed. If false, the buildings
will not be revealed. Note that if you set it to false, it will not hide the buildings with a black mask.
*/
native CripplePlayer takes player whichPlayer, force toWhichPlayers, boolean flag returns nothing
```

--------------------------------

### Annotations added by mksrc script

Source: https://context7.com/luashine/jassdoc/llms.txt

Example of annotations inserted per symbol by the `mksrc` script, including 'source-code', 'start-line', and 'end-line' for function, native, global, and type declarations.

```sql
# Inserted annotations per symbol (example for a native):
# INSERT INTO annotations (fnname, anname, value) VALUES
#   ('TimerStart', 'source-code', 'native TimerStart takes timer whichTimer, real timeout, boolean periodic, code handlerFunc returns nothing');
# INSERT INTO annotations (fnname, anname, value) VALUES
#   ('TimerStart', 'start-line', '11988');
# INSERT INTO annotations (fnname, anname, value) VALUES
```

--------------------------------

### Lua: Reading Player Properties

Source: https://context7.com/luashine/jassdoc/llms.txt

Reads various properties of a player, such as their name, color, team, and start location. Provides notes on neutral player indices for different game versions.

```lua
-- Lua: read player properties
local name  = GetPlayerName(Player(0))     --> "YourName"
local color = GetPlayerColor(Player(0))    --> playercolor handle
local team  = GetPlayerTeam(Player(0))     --> integer team index
local slot  = GetPlayerStartLocation(Player(0))  --> integer or -1

-- Neutral players (index differs Classic vs Reforged):
--   Classic:   PLAYER_NEUTRAL_PASSIVE = 15,  PLAYER_NEUTRAL_AGGRESSIVE = 12
--   Reforged:  PLAYER_NEUTRAL_PASSIVE = 27,  PLAYER_NEUTRAL_AGGRESSIVE = 24
-- Use GetPlayerNeutralPassive() / GetBJMaxPlayers() for portable code (patch 1.29+).
print(GetPlayerName(Player(PLAYER_NEUTRAL_PASSIVE)))  --> "Player 28"
```

--------------------------------

### JASS Common Game Object Type Hierarchy

Source: https://context7.com/luashine/jassdoc/llms.txt

Illustrates the inheritance hierarchy for JASS game objects, starting from the base 'handle' type. Highlights the 'widget' branch and its subtypes.

```jass
handle
├── agent                  -- reference-counted; most game objects
│   ├── event              -- trigger event registration (no useful standalone API)
│   ├── player             -- a single player slot
│   ├── widget             -- interactive game object with HP
│   │   ├── unit           -- a single unit
│   │   ├── destructable   -- tree, bridge, etc.
│   │   └── item           -- an item on the ground or in inventory
│   ├── ability / buff
│   ├── force              -- group of players
│   ├── group              -- group of units
│   ├── trigger / triggercondition
│   ├── timer
│   ├── location / region / rect
│   ├── effect             -- visual special effect
│   ├── fogmodifier / dialog / button / quest
│   ├── hashtable          -- key-value store; used for type-casting
│   └── framehandle        -- UI frame (patch 1.31+)
└── handle (direct)
    ├── race / alliancetype / gamespeed / gamedifficulty / gametype
    ├── eventid / gameevent / playerevent / playerunitevent / unitevent
    ├── attacktype / damagetype / weapontype / pathingtype
    ├── camerafield / camerasetup / playercolor
    ├── abilityintegerfield / abilityrealfield / ...  (object data fields, patch 1.31+)
    └── framehandle (wrong type bug: should extend agent)

-- Type-casting via hashtable (downcasting widget → unit):
hasht = InitHashtable()
SaveWidgetHandle(hasht, 1, 1, widgetHandle)   -- store as widget
local u = LoadUnitHandle(hasht, 1, 1)         -- retrieve as unit
```

--------------------------------

### Build Project with Make

Source: https://github.com/luashine/jassdoc/blob/master/Readme.md

Build the jass.db project by cloning the repository and running 'make'. Requires GHC, cabal, gnu make, and the sqlite3 cli binary.

```bash
make
```

--------------------------------

### Build the JASS database with make

Source: https://context7.com/luashine/jassdoc/llms.txt

Builds the `jass.db` database using `make`. This process requires GHC/cabal, make, and sqlite3.

```bash
# Build the database (requires GHC/cabal, make, sqlite3)
make           # produces jass.db
```

--------------------------------

### JassDoc Build and Toolchain Usage (Bash)

Source: https://context7.com/luashine/jassdoc/llms.txt

Commands for building the `jass.db` SQLite database from annotated source files using GHC, make, and other tools. Includes steps for parsing, appending annotations and metadata, and quality checks.

```bash
# Prerequisites: GHC + cabal, GNU make, sqlite3, perl (v5.30+)

# Full build (produces jass.db):
make

# Step-by-step:
# 1. Parse .j files and emit SQL with mkdocs (Haskell):
cabal run mkdocs -- --output db.sql common.j Blizzard.j common.ai builtin-types.j

# 2. Append source-code / line-number annotations (Perl):
perl mksrc common.j Blizzard.j common.ai builtin-types.j >> db.sql

# 3. Append build metadata (git revision, timestamp):
sh mkmetadata >> db.sql

# 4. Create SQLite database:
sqlite3 jass.db < db.sql

# Quality checks:
make check-missing   # list functions without documentation
make check-params    # verify @param tags match actual parameters
make check-git-revision  # verify DB was built from current commit

# Nix build (no manual dependency installation):
nix build github:lep/jassdoc
```

--------------------------------

### Run mkdocs manually to generate SQL

Source: https://context7.com/luashine/jassdoc/llms.txt

Manually runs the `mkdocs` executable to process JASS files and generate an SQL script for populating `jass.db`. It creates DELETE and INSERT statements for annotations, parameters, and params_extra tables.

```bash
# Run mkdocs manually:
cabal run mkdocs -- --output db.sql common.j Blizzard.j common.ai builtin-types.j
```

--------------------------------

### SQL structure generated by mkdocs

Source: https://context7.com/luashine/jassdoc/llms.txt

Illustrates the SQL structure generated by `mkdocs` for each symbol, including DELETE statements for existing data and INSERT statements for annotations, parameters, and parameter extras.

```sql
# db.sql structure (per symbol):
# DELETE FROM parameters  WHERE fnname = 'CreateUnit';
# DELETE FROM annotations WHERE fnname = 'CreateUnit';
# INSERT INTO annotations VALUES ('CreateUnit', 'comment', 'Creates a unit...');
# INSERT INTO annotations VALUES ('CreateUnit', 'param',   'id unit type rawcode');
# INSERT INTO annotations VALUES ('CreateUnit', 'patch',   '1.00');
# INSERT INTO annotations VALUES ('CreateUnit', 'source-file', 'common.j');
# INSERT INTO annotations VALUES ('CreateUnit', 'return-type', 'unit');
# INSERT INTO params_extra VALUES ('CreateUnit', 'id', 'param_order', 1);
# INSERT INTO params_extra VALUES ('CreateUnit', 'id', 'param_type',  'integer');
```

--------------------------------

### Manually Extract Lua Data

Source: https://github.com/luashine/jassdoc/blob/master/extra-lua/README.md

These commands demonstrate a manual method for extracting Lua data using standard Unix utilities. This approach is useful for inspecting game data directly.

```bash
export w3exe="$(cygpath 'D:\\SteamLibrary\\Warcraft III\\_retail_\\x86_64\\Warcraft III.exe')"
strings --data -n 8 -t d "$w3exe" | grep -C2 --color -i __jarray
```

```bash
tail --bytes +12345 "$w3exe" | strings -n 1 | head -n 80
```

--------------------------------

### Lua: Group Enumeration and Unit Commands

Source: https://context7.com/luashine/jassdoc/llms.txt

Collects all living enemy units within a specified range and iterates through them to issue an order. Using ForGroup is recommended for safe iteration over group members.

```lua
-- Lua: collect all living enemy units within 500 range of (0,0)
local g = CreateGroup()
GroupEnumUnitsInRange(g, 0, 0, 500, nil)   -- nil filter = add all units

-- Iterate and issue an order to each
ForGroup(g, function()
    local u = GetEnumUnit()
    if GetUnitState(u, UNIT_STATE_LIFE) > 0 then
        IssueImmediateOrder(u, "stop")
    end
end)

-- FirstOfGroup pitfall: returns null if index-0 unit was removed from game
-- even when later indices hold valid units. Use ForGroup for safe iteration.
local first = FirstOfGroup(g)   -- may be null even if #group > 0

DestroyGroup(g)   -- release memory
```

--------------------------------

### Player API

Source: https://context7.com/luashine/jassdoc/llms.txt

Functions for configuring and querying player properties such as alliances, names, colors, and resources.

```APIDOC
## Player API

Functions to configure and query player slots, alliances, names, colors, and resources.

```jass
// Share vision of blue's units to red (note reversed semantics)
function ShowBlueToRed takes nothing returns nothing
    local player red  = Player(0)
    local player blue = Player(1)
    // "blue's vision is shared to red"
    call SetPlayerAlliance(blue, red, ALLIANCE_SHARED_VISION, true)
endfunction
```

```lua
-- Lua: read player properties
local name  = GetPlayerName(Player(0))     --> "YourName"
local color = GetPlayerColor(Player(0))    --> playercolor handle
local team  = GetPlayerTeam(Player(0))     --> integer team index
local slot  = GetPlayerStartLocation(Player(0))  --> integer or -1

-- Neutral players (index differs Classic vs Reforged):
--   Classic:   PLAYER_NEUTRAL_PASSIVE = 15,  PLAYER_NEUTRAL_AGGRESSIVE = 12
--   Reforged:  PLAYER_NEUTRAL_PASSIVE = 27,  PLAYER_NEUTRAL_AGGRESSIVE = 24
-- Use GetPlayerNeutralPassive() / GetBJMaxPlayers() for portable code (patch 1.29+).
print(GetPlayerName(Player(PLAYER_NEUTRAL_PASSIVE)))  --> "Player 28"
```
```

--------------------------------

### Extra / Hidden API

Source: https://context7.com/luashine/jassdoc/llms.txt

Documents game API that exists in the binary but is not declared in `common.j`.

```APIDOC
## Extra / Hidden API (`extra-jass/`)

Documents game API that exists in the binary but is not declared in `common.j`.

```lua
-- extra-jass/reforged-hidden.j
-- BlzDeleteHeroAbility: removes ability without refunding skill points.
-- In JASS, the native declaration must appear before any other functions:
--   native BlzDeleteHeroAbility takes unit unitHandle, integer abilID returns nothing

-- Lua example (no declaration needed):
local hero = CreateUnit(Player(0), FourCC("Otch"), -100, 0, 90)
UnitAddAbility(hero, FourCC("AOws"))  -- add tauren stomp
BlzDeleteHeroAbility(hero, FourCC("AOws"))  -- instantly removed, no refund

-- Bug: on regular (non-hero) units the UI icon is not refreshed immediately.
local foot = CreateUnit(Player(0), FourCC("hfoo"), 200, 0, 90)
UnitAddAbility(foot, FourCC("AHab"))
BlzDeleteHeroAbility(foot, FourCC("AHab"))  -- works, but icon lingers until UI refresh

-- BlzGetDestructableSkin: returns current skin rawcode
local tree = CreateDestructable(FourCC("ATtr"), -256, 256, 180.0, 1.0, 0)
print(BlzGetDestructableSkin(tree))  --> 1096053874 == FourCC("ATtr")
```
```

--------------------------------

### Run mksrc script to append source-code annotations

Source: https://context7.com/luashine/jassdoc/llms.txt

Appends source-code, start-line, end-line, and type annotations to `db.sql` for JASS declarations. This script is called automatically by `GNUmakefile` after `mkdocs`.

```bash
# Called automatically from GNUmakefile after mkdocs:
perl mksrc common.j Blizzard.j common.ai builtin-types.j >> db.sql
```

--------------------------------

### Timer API

Source: https://context7.com/luashine/jassdoc/llms.txt

Functions for creating, managing, and interacting with timers in Warcraft 3. Timers offer high-resolution periodic events.

```APIDOC
## Timer API

Create, start, pause, resume, and query timers. Timers are the highest-resolution periodic mechanism (up to ~10 000 Hz), significantly faster than trigger-based periodic events in classic Warcraft 3.

```jass
// JASS: one-shot timer example
function OnExpire takes nothing returns nothing
    local timer t = GetExpiredTimer()
    call DestroyTimer(t)
    // ... do work ...
endfunction

function StartMyTimer takes nothing returns nothing
    local timer t = CreateTimer()
    call TimerStart(t, 5.0, false, function OnExpire)
    // t will fire once after 5 game-seconds
endfunction
```

```lua
-- Lua: periodic 0.1-second timer
local t = CreateTimer()
TimerStart(t, 0.1, true, function()
    -- runs every 100 ms
    local elapsed = TimerGetElapsed(t)   -- time since last reset
    local remain  = TimerGetRemaining(t) -- time until next expiry
end)

-- Bug note: DestroyTimer does NOT pause the timer; the callback may
-- still fire once after destruction with GetExpiredTimer() == nil.
-- Bug note: PauseTimer clears the periodic flag.
```
```

--------------------------------

### SQLite Database Schema for Jass Documentation

Source: https://context7.com/luashine/jassdoc/llms.txt

Defines the tables and indexes for storing Jass annotations, parameters, and build metadata. Used for organizing and querying documentation information.

```sql
-- schema.sql
CREATE TABLE IF NOT EXISTS parameters (
    fnname text,
    param  text,
    value  text,
    PRIMARY KEY (fnname, param)
);

CREATE TABLE IF NOT EXISTS annotations (
    fnname text,
    anname text,   -- 'comment', 'param', 'bug', 'note', 'patch', 'source-code', ...
    value  text
);

CREATE INDEX IF NOT EXISTS annotation_index ON annotations(fnname);

CREATE TABLE IF NOT EXISTS params_extra (
    fnname text,
    param  text,
    anname text,   -- 'param_order' (integer) or 'param_type' (string)
    value,
    PRIMARY KEY (fnname, param, anname)
);

CREATE TABLE IF NOT EXISTS metadata (
    key   text PRIMARY KEY,
    value text
);
```

--------------------------------

### Jass Annotation with Link

Source: https://github.com/luashine/jassdoc/blob/master/Readme.md

Shows how to include a hyperlink within a Jass annotation note, linking to an external discussion about the function.

```jass
/**
@note
Same as above, but on the next line, with a [link](http://example.com/function-discussion)
*/
```

--------------------------------

### Parse a complete JASS file with Jass.Parser

Source: https://context7.com/luashine/jassdoc/llms.txt

Parses a JASS file using the `programm` parser from `Jass.Parser`. Handles successful parsing by processing top-level declarations or reports errors.

```haskell
-- Parse a complete JASS file
import Text.Megaparsec (parse, errorBundlePretty)
import Jass.Parser (programm)

result <- parse programm "common.j" . (++ "\n") <$> readFile "common.j"
case result of
  Right (Programm toplevels) -> mapM_ processTopLevel toplevels
  Left err                   -> error (errorBundlePretty err)

-- Individual parsers available for composition:
-- expression  :: Parser (Ast Annotations Expr)
-- statement   :: Parser (Ast Annotations Stmt)
-- toplevel    :: Parser [Ast Annotations Toplevel]
-- docstring   :: Parser Annotations          -- parses /** ... */ blocks
-- identifier  :: Parser String
-- intlit      :: Parser String               -- decimal, hex ($FF), octal, char, FourCC ('hfoo')
-- reallit     :: Parser String
-- stringlit   :: Parser String
-- rawcode     :: Parser String               -- 'XXXX' four-char codes
```

--------------------------------

### JASS: Group Filtering with BoolExpr

Source: https://context7.com/luashine/jassdoc/llms.txt

Demonstrates using a BoolExpr to filter units during group enumeration in JASS. Remember to destroy the BoolExpr and Group when they are no longer needed.

```jass
// JASS: group filter via boolexpr
function IsEnemy takes nothing returns boolean
    return IsUnitEnemy(GetFilterUnit(), Player(0))
endfunction

function EnumEnemies takes nothing returns nothing
    local group g = CreateGroup()
    local boolexpr f = Filter(function IsEnemy)
    call GroupEnumUnitsInRect(g, bj_mapInitialPlayableArea, f)
    call DestroyBoolExpr(f)
    call ForGroup(g, function DoWork)
    call DestroyGroup(g)
endfunction
```

--------------------------------

### Read/Write Unit Integer Fields (Lua)

Source: https://context7.com/luashine/jassdoc/llms.txt

Use `BlzGetUnitIntegerField` and `BlzSetUnitIntegerField` to read and write integer data fields for units. Note that many string fields are read-only or may fail silently.

```lua
local u = CreateUnit(Player(0), FourCC("Hamg"), 0, 0, 270)

-- Read current strength
local str = BlzGetUnitIntegerField(u, UNIT_IF_STRENGTH_WITH_BONUS)
print("Strength:", str)

-- Set unit level (base data, not hero level)
BlzSetUnitIntegerField(u, UNIT_IF_LEVEL, 10)

-- Ability fields (level-independent)
local abil = BlzGetUnitAbility(u, FourCC("AHbz"))
BlzSetAbilityIntegerField(abil, ABILITY_IF_LEVELS, 3)

-- String fields: many silently fail; 'unam' (UNIT_SF_NAME) works:
local sf = ConvertUnitStringField(FourCC("unam"))
BlzSetUnitStringField(u, sf, "Archmage Supreme")
print(BlzGetUnitStringField(u, sf))  --> "Archmage Supreme"

-- Fields that do NOT work: umdl (model), uico (icon), ua1m (projectile art)
```

--------------------------------

### Group API

Source: https://context7.com/luashine/jassdoc/llms.txt

Functions for managing groups of units, including enumeration, iteration, and issuing commands.

```APIDOC
## Group API — Unit Enumeration and Commands

Groups are ordered collections of units. The three main enumeration functions (`GroupEnumUnitsInRect`, `GroupEnumUnitsInRange`, `GroupEnumUnitsSelected`) clear the group then fill it using an optional filter. `ForGroup` iterates without order guarantees; `FirstOfGroup` gives direct access.

```lua
-- Lua: collect all living enemy units within 500 range of (0,0)
local g = CreateGroup()
GroupEnumUnitsInRange(g, 0, 0, 500, nil)   -- nil filter = add all units

-- Iterate and issue an order to each
ForGroup(g, function()
    local u = GetEnumUnit()
    if GetUnitState(u, UNIT_STATE_LIFE) > 0 then
        IssueImmediateOrder(u, "stop")
    end
end)

-- FirstOfGroup pitfall: returns null if index-0 unit was removed from game
-- even when later indices hold valid units. Use ForGroup for safe iteration.
local first = FirstOfGroup(g)   -- may be null even if #group > 0

DestroyGroup(g)   -- release memory
```

```jass
// JASS: group filter via boolexpr
function IsEnemy takes nothing returns boolean
    return IsUnitEnemy(GetFilterUnit(), Player(0))
endfunction

function EnumEnemies takes nothing returns nothing
    local group g = CreateGroup()
    local boolexpr f = Filter(function IsEnemy)
    call GroupEnumUnitsInRect(g, bj_mapInitialPlayableArea, f)
    call DestroyBoolExpr(f)
    call ForGroup(g, function DoWork)
    call DestroyGroup(g)
endfunction
```
```

--------------------------------

### Jassdoc Comment Template

Source: https://github.com/luashine/jassdoc/blob/master/Readme.md

A template for Jassdoc comments, outlining general description, parameters, bug reporting, custom notes, and asynchronous/event/patch information. Fill out or remove applicable sections.

```jassdoc
/**
GENERAL_DESCRIPTION

@param VARIABLE_1_NAME VARIABLE_1_EXPLANATION

@bug DESCRIBE_BUGGY_BEHAVIOUR_IF_ANY

@note ADD_YOUR_CUSTOM_NOTE

@async / @event EVENT_NAME / @patch PATCH_VERSION
*/
```

--------------------------------

### Object Data Field API

Source: https://context7.com/luashine/jassdoc/llms.txt

Read and write object editor data fields at runtime using unit*, ability*, and item* typed constants. Many string fields are read-only or silently fail.

```APIDOC
## Object Data Field API (`BlzGet/SetUnitIntegerField`, patch 1.31+)

Read and write object editor data fields at runtime using `unit*field`, `ability*field`, and `item*field` typed constants. Many string fields are read-only or silently fail.

```lua
-- Lua: read/write unit integer fields
local u = CreateUnit(Player(0), FourCC("Hamg"), 0, 0, 270)

-- Read current strength
local str = BlzGetUnitIntegerField(u, UNIT_IF_STRENGTH_WITH_BONUS)
print("Strength:", str)

-- Set unit level (base data, not hero level)
BlzSetUnitIntegerField(u, UNIT_IF_LEVEL, 10)

-- Ability fields (level-independent)
local abil = BlzGetUnitAbility(u, FourCC("AHbz"))
BlzSetAbilityIntegerField(abil, ABILITY_IF_LEVELS, 3)

-- String fields: many silently fail; 'unam' (UNIT_SF_NAME) works:
local sf = ConvertUnitStringField(FourCC("unam"))
BlzSetUnitStringField(u, sf, "Archmage Supreme")
print(BlzGetUnitStringField(u, sf))  --> "Archmage Supreme"

-- Fields that do NOT work: umdl (model), uico (icon), ua1m (projectile art)
```
```

--------------------------------

### JASS: Player Alliance - Shared Vision

Source: https://context7.com/luashine/jassdoc/llms.txt

Configures player alliances to share vision between two players. Note the reversed semantics in the function call.

```jass
// Share vision of blue's units to red (note reversed semantics)
function ShowBlueToRed takes nothing returns nothing
    local player red  = Player(0)
    local player blue = Player(1)
    // "blue's vision is shared to red"
    call SetPlayerAlliance(blue, red, ALLIANCE_SHARED_VISION, true)
endfunction
```

--------------------------------

### Remove Hero Ability (Lua)

Source: https://context7.com/luashine/jassdoc/llms.txt

Use `BlzDeleteHeroAbility` to remove an ability from a hero without refunding skill points. For regular units, the UI icon may not refresh immediately.

```lua
-- extra-jass/reforged-hidden.j
-- BlzDeleteHeroAbility: removes ability without refunding skill points.
-- In JASS, the native declaration must appear before any other functions:
--   native BlzDeleteHeroAbility takes unit unitHandle, integer abilID returns nothing

-- Lua example (no declaration needed):
local hero = CreateUnit(Player(0), FourCC("Otch"), -100, 0, 90)
UnitAddAbility(hero, FourCC("AOws"))  -- add tauren stomp
BlzDeleteHeroAbility(hero, FourCC("AOws"))  -- instantly removed, no refund

-- Bug: on regular (non-hero) units the UI icon is not refreshed immediately.
local foot = CreateUnit(Player(0), FourCC("hfoo"), 200, 0, 90)
UnitAddAbility(foot, FourCC("AHab"))
BlzDeleteHeroAbility(foot, FourCC("AHab"))  -- works, but icon lingers until UI refresh
```

--------------------------------

### JASS AST Data Types

Source: https://context7.com/luashine/jassdoc/llms.txt

Defines the Generic Algebraic Data Type (GADT) `Ast ann a` for representing JASS abstract syntax trees, with `ann` for annotations and `a` constraining node kinds.

```haskell
-- Toplevel declarations
data Ast ann a where
  Programm  :: [Ast ann Toplevel]                              -> Ast ann Programm
  Native    :: ann -> Constant -> Name -> [(Type,Name)] -> Type -> Ast ann Toplevel
  Function  :: ann -> Constant -> Name -> [(Type,Name)] -> Type -> [Ast ann Stmt] -> Ast ann Toplevel
  Global    :: Ast ann VarDef                                  -> Ast ann Toplevel
  Typedef   :: ann -> Type -> Type                             -> Ast ann Toplevel
  -- Variable definitions
  SDef :: ann -> Constant -> Name -> Type -> Maybe (Ast ann Expr) -> Ast ann VarDef
  ADef :: ann -> Name -> Type                                  -> Ast ann VarDef
  -- Statements
  Set      :: Ast ann LVar -> Ast ann Expr                     -> Ast ann Stmt
  If       :: Ast ann Expr -> [Ast ann Stmt]
           -> [(Ast ann Expr, [Ast ann Stmt])] -> Maybe [Ast ann Stmt] -> Ast ann Stmt
  Loop     :: [Ast ann Stmt]                                   -> Ast ann Stmt
  Exitwhen :: Ast ann Expr                                     -> Ast ann Stmt
  Return   :: Maybe (Ast ann Expr)                             -> Ast ann Stmt
  Call     :: Name -> [Ast ann Expr]                           -> Ast ann a
  -- Expressions
  Var    :: Ast ann LVar -> Ast ann Expr
  Int    :: Stringtype   -> Ast ann Expr   -- "42", "$FF", "'hfoo'"
  Real   :: Stringtype   -> Ast ann Expr
  Bool   :: Bool         -> Ast ann Expr
  String :: Stringtype   -> Ast ann Expr
  Null   ::                 Ast ann Expr
  Code   :: Name         -> Ast ann Expr   -- function reference
```

--------------------------------

### Haskell parseDocstring function

Source: https://context7.com/luashine/jassdoc/llms.txt

This Haskell code defines the `parseDocstring` function, which parses Javadoc-style comment blocks into a structured list of key-value pairs.

```haskell
-- Annotation.hs
parseDocstring :: L8.ByteString -> Annotations
-- Returns: Annotations [("comment", "..."), ("param", "x description"), ("bug", "..."), ...]

-- Example input (raw docstring body after stripping /** and */):
-- "Does X\n\n@param x the value
@bug broken in 1.00"
-- Result: [("comment","Does X"), ("param","x the value"), ("bug","broken in 1.00")]

-- ToJSON instance emits pairs as [[key, value], ...] filtering empty values:
-- [["comment","Does X"],["param","x the value"],["bug","broken in 1.00"]]
```

--------------------------------

### JASS Built-in Primitive Types

Source: https://context7.com/luashine/jassdoc/llms.txt

Defines the five fundamental Jass types: handle, code, boolean, real, and integer. Note the specific behavioral quirks mentioned for boolean and real types.

```jass
type handle  extends void   -- base reference type; all game objects extend handle
type code    extends void   -- function reference type
type boolean extends void   -- true/false; prefer literal 'true' over constant TRUE
type real    extends void   -- 32-bit IEEE-754 float; equality precision is 0.001
type integer extends void   -- 32-bit two's complement

-- integer literal forms:
-- Decimal:     42, -7
-- Hex:         $FF  or  0xFF
-- Octal:       0777  (Lua: NOT supported by Jass2Lua compiler)
-- Character:   'A'  --> 65
-- FourCC:      'hfoo'  --> human footman unit type ID
--              In Lua use: FourCC("hfoo")  instead of 'hfoo'
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.