wowsims/wotlk

To enable autocompletion for Action Priority List (APL) files in VS Code, you must generate a JSON schema from the project's protobuf definitions. This allows VS Code to validate your .apl.json files against the expected structure.

1. Install the JSON schema generator: Run the following command to install protoc-gen-jsonschema via Go:

   go install github.com/chrusty/protoc-gen-jsonschema/cmd/protoc-gen-jsonschema@latest

2. Generate the Schema: Create a jsonschema directory and use protoc to generate the schema from the APL proto file:

   mkdir jsonschema
   protoc \
     --jsonschema_out=./jsonschema \
     --proto_path=./proto/ \
     --jsonschema_opt=json_fieldnames \
     --jsonschema_opt=enforce_oneof \
     --jsonschema_opt=disallow_additional_properties \
     ./proto/apl.proto

3. Configure VS Code: Ensure your .vscode/settings.json points to the generated jsonschema directory. The extension .apl.json will then automatically activate the schema for autocompletion.

To develop locally on Ubuntu, you must install Go (>=1.21), a protobuf-compiler with Go plugins, and Node (>=14.0).

Warning: Do not use apt to install these dependencies as the versions provided by apt are too old. Use the following script to install the correct versions via curl and nvm.

# Standard Go installation script
curl -O https://dl.google.com/go/go1.21.1.linux-amd64.tar.gz
sudo rm -rf /usr/local/go 
sudo tar -C /usr/local -xzf go1.21.1.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> $HOME/.bashrc
echo 'export GOPATH=$HOME/go' >> $HOME/.bashrc
echo 'export PATH=$PATH:$GOPATH/bin' >> $HOME/.bashrc
source $HOME/.bashrc

cd wotlk

# Install protobuf compiler and Go plugins
sudo apt update && sudo apt upgrade
sudo apt install protobuf-compiler
go get -u -v google.golang.org/protobuf
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest

# Install node
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
nvm install 19.8.0

# Install the npm package dependencies using node
npm install

Adding a new simulation involves three main phases: defining the data interface, implementing the UI, and implementing the simulation logic.

1. Create the Proto Interface

Use Protocol Buffers to define the data structure shared between Go and TypeScript:

• Add a new value to the Spec enum in proto/common.proto. This name (e.g., elemental_shaman) is used for templating as $SPEC.
• Create proto/YOUR_CLASS.proto with class-specific data messages.
• Update PlayerOptions.spec in proto/api.proto to include your new message.
• Running make will then generate the necessary .go and .ts code.

2. Implement the UI

• Modify ui/core/proto_utils/utils.ts to include boilerplate for your $SPEC.
• Create a directory ui/$SPEC (e.g., ui/elemental_shaman).
• Copy existing spec UI code as a template and modify the files.
• Add a rule to the makefile for your new spec.
• Run make host and visit http://localhost:8080/wotlk/$SPEC.

3. Implement the Sim

• sim/core/api.go: Implement the request/response messages from proto/api.proto.
• sim/core/sim.go: Orchestrates the simulation; the main loop is in Simulation.RunOnce.
• sim/core/agent.go: Implement the Agent interface (the 'Player' logic).
• sim/core/character.go: Manages stats, cooldowns, and gear.
• Registration: Add your new sim to RegisterAll() in sim/register_all.go.
• Testing: Write unit tests and run them with make test.

APL (Action Priority List) files should use the .apl.json extension. An empty rotation file follows this structure:

{
    "type": "TypeAPL",
    "prepullActions": [],
    "priorityList": []
}

Prepull Actions

Prepull actions are executed before the main rotation. For example, to cast a spell 1 second before the rotation starts:

{
    "action": {
        "castSpell": {
            "spellId": {
                "spellId": 1
            }
        }
    },
    "doAt": "-1s"
}

Priority List Actions and Conditions

Actions in the priorityList can include conditions using the cmp (compare) object. The cmp object uses op (operator), lhs (left hand side), and rhs (right hand side).

Example: Checking if the remaining time on a Flame Shock dot is greater than the cast time of Lava Burst (OpGt) before casting Lava Burst:

{
    "action": {
        "condition": {
            "cmp": {
                "op": "OpGt",
                "lhs": {
                    "dotRemainingTime": {
                        "spellId": {
                            "spellId": 49233
                        }
                    }
                },
                "rhs": {
                    "spellCastTime": {
                        "spellId": {
                            "spellId": 60043
                        }
                    }
                }
            }
        },
        "castSpell": {
            "spellId": {
                "spellId": 60043
            }
        }
    }
}

For long-running tasks like raidSimAsync, statWeightsAsync, and bulkSimAsync, the simulator uses an asynchronous pattern to report progress back to the JavaScript environment.

To use these functions:

1. Pass the simulation request as the first argument (args[0]).
2. Pass a JavaScript callback function as the second argument (args[1]).
3. The simulator will invoke your callback function repeatedly, passing a Uint8Array containing serialized proto.ProgressMetrics for each update.
4. The callback will be invoked one final time with the final result once the simulation completes.

// Example: Using raidSimAsync with a progress callback
const requestBinary = new Uint8Array([...]); // Serialized RaidSimRequest

raidSimAsync(requestBinary, (progressBytes) => {
  // progressBytes is a Uint8Array containing proto.ProgressMetrics
  // You would typically decode this using protobufjs or similar
  console.log("Progress update received");
});

The simulator can be run as a web server that hosts the user interface and provides simulation APIs via Protobuf over HTTP. You can configure the server using several command-line flags.

CLI Flags

• -usefs: Set to true to use the local ./dist directory for client files instead of the embedded filesystem. Useful for local development.
• -wasm: Use WebAssembly for the simulation instead of web server APIs. Note: This requires -usefs=true to be set.
• -sim: The name of the specific simulator to launch (e.g., balance_druid, elemental_shaman). This determines the default URL path.
• -host: The URL/address to host the interface on (default: localhost:3333).
• -launch: Whether to automatically open the browser (default: true).
• -nvc: Skip the version check against GitHub releases.

# Example: Running with local files and a specific sim name
./wotlk-sim -usefs=true -sim=elemental_shaman