War3Net Toolkit

War3Net is a .NET toolkit for Warcraft III modding, providing tools for low-level file formats (MPQ, BLP) and high-level map building. It consists of three main components:

1. NuGet packages: The core foundation, with individual packages covering specific file formats or concerns (e.g., MPQ, JASS, map building).
2. Command-line tool (w3n): A CLI that exposes package functionality for scripting, CI, or terminal use (Coming soon™).
3. VS Code extension (War3Net Toolkit): An editor extension built on top of the CLI to bring file format support directly into the IDE (Coming soon™).

The initial release (v1.0.0) of War3Net.CodeAnalysis.Jass provides the following core capabilities for JASS development:

• Parsing: Use JassParser and JassSyntaxFactory to convert JASS source code into a syntax tree.
• Rendering: Use JassRenderer and JassRendererOptions to convert a syntax tree back into JASS source code.
• Transpilation: Use JassTranspiler and JassTranspilerHelper to transpile JASS to C# (including support for attributes used in C#-to-Lua steps).
• Obfuscation: Includes a source code obfuscator for JASS.

Since version v5.0.0, the architecture of map and campaign data has changed significantly. Data classes (like Map and Campaign) are now plain mutable data objects.

Parsing and serialization are no longer methods on the classes themselves; instead, they are implemented via binary reader/writer extension methods. This separation of data and logic is a core design pattern in the current version of the library.

War3Net v6.0.0 introduces a redesigned syntax model in War3Net.CodeAnalysis.Jass designed for byte-for-byte accuracy. This model allows for parsing and re-rendering JASS while preserving exact source formatting, including whitespace, newlines, and comments.

Key components of the new syntax model:

• JassSyntaxToken: Represents tokens that include leading and trailing trivia.
• JassSyntaxTrivia: Represents non-semantic elements like whitespace, newlines, and comments.
• JassSyntaxKind: A unified enum used to identify literals, operators, and keywords.

When manipulating SylkTable objects, keep the following rules in mind:

• Zero-based Indexing: Rows, Columns, and the cell indexer are all 0-indexed.
• Cell Nullability: Setting a cell to null triggers a recalculation of the table's Rows and Columns properties to ensure they remain accurate.
• Shrinking Tables: Use SylkTable.Shrink to reduce table size. (Note: Ensure you are using v0.1.2 or later to avoid bugs where the last row/column was clipped).

The initial release (v0.1.0) established the following core capabilities for building Warcraft III map files from source:

• MapBuilder: Assembles a map from its data files and assets, including the ability to load assets from MPQ archives.
• ScriptCompiler & ScriptCompilerOptions: Compiles map scripts from JASS, Lua, or C#. Supports importing custom Lua libraries and compiling C# in debug mode.
• FunctionBuilder: Classes used for generating the main and config functions.
• war3map.w3i Parsing/Serialization: Provides methods to manipulate player and force settings.
• Environment & Tilesets: Includes the Tileset enum, provider classes for light and sound environments, and a FileProvider with locale support.

The library is built around three core types:

• SylkParser: Responsible for parsing SLK file streams into SylkTable objects.
• SylkTable: An in-memory representation of a tabular spreadsheet providing cell access and query operations.
• SylkSerializer: Responsible for serializing SylkTable objects back into the SLK format.

As of War3Net.Build v6.0.0, the following architectural changes apply to script generation:

• MapScriptBuilder: Methods now write to an IndentedTextWriter rather than returning a syntax object. The direct C# API methods are removed; use GenerateGlobals and manual transpilation for C# workflows.
• Trigger Rendering: TriggerRenderer and TriggerRendererContext now require an IndentedTextWriter for output.

When upgrading to War3Net.CodeAnalysis.Decompilers v6.0.0 or higher, note that War3Net.CodeAnalysis.Jass has also been updated to v6.0.0.

Breaking Change: The TryDecompile* overloads that accept a JassFunctionDeclarationSyntax now expect redesigned syntax classes. You must update your code to use the new syntax classes. Refer to the official Jass migration guide for detailed instructions.

War3Net v6.0.0 contains several breaking changes due to the JASS engine rework. If you are upgrading from v5, you must address the following architectural shifts:

1. Interface to Abstract Class Transition: Many interfaces have been replaced by abstract classes. For example, IExpressionSyntax is now JassExpressionSyntax.
2. Literal Handling: Specific literal syntax classes have been replaced by a generic JassLiteralExpressionSyntax which uses JassSyntaxKind to differentiate types.
3. Operator Identification: Operator enums have been replaced by token kinds. For example, instead of using BinaryOperatorType.Add, you should use JassSyntaxKind.PlusToken.

For a complete list of changes, refer to the official migration guide.

To create a new table, instantiate SylkTable(int columns, int rows). You can set cell values using the [column, row] indexer. To save the table, use SylkSerializer with the SerializeTo(Stream, bool leaveOpen) method.

using War3Net.IO.Slk;

// Create a new table with dimensions
var table = new SylkTable(3, 4); // 3 columns, 4 rows

// Set header row
table[0, 0] = "ID";
table[1, 0] = "Name";
table[2, 0] = "Value";

// Set data rows
table[0, 1] = "A001";
table[1, 1] = "First Item";
table[2, 1] = 100;

// Serialize to a stream
using var output = File.Create("output.slk");
new SylkSerializer(table).SerializeTo(output, leaveOpen: false);