Update Docs, Add Docker Releases & ARM64 Support

.github/workflows/release.yml

@@ -1,8 +1,8 @@
 name: Release
 
 on:
+    # Inputs the workflow accepts.
     workflow_dispatch:
-        # Inputs the workflow accepts.
         inputs:
             ref:
                 description: 'Commit Reference'
@@ -13,12 +13,19 @@ on:
                 default: 'v0.0.0'
                 required: true
 
+env:
+    REGISTRY: ghcr.io
+    IMAGE_NAME: ${{ github.repository }}
+
 jobs:
     build-and-release:
         runs-on: ubuntu-latest
         permissions:
             contents: write
+            packages: write
+
         steps:
+            # Build Dependencies
             - name: Install Go
               uses: actions/setup-go@v2
               with:
@@ -38,6 +45,30 @@ jobs:
               with:
                   node-version: 20
 
+            # Setup Docker
+            - name: Setup QEMU
+              uses: docker/setup-qemu-action@v3
+
+            - name: Set up Docker Buildx
+              uses: docker/setup-buildx-action@v3
+
+            - name: Log in to the Container registry
+              uses: docker/login-action@v3
+              with:
+                  registry: ${{ env.REGISTRY }}
+                  username: ${{ github.actor }}
+                  password: ${{ secrets.GITHUB_TOKEN }}
+
+            - name: Extract metadata
+              id: meta
+              uses: docker/metadata-action@v5
+              with:
+                  images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+                  tags: |
+                      type=raw,value=latest
+                      type=raw,value=${{ github.event.inputs.tag }}
+
+            # Checkout, test and build
             - name: Checkout
               uses: actions/[email protected]
               with:
@@ -51,6 +82,17 @@ jobs:
               run: |
                   make clean && VERSION=${{ github.event.inputs.tag }} make release
 
+            # Release
+            - name: Build and push Docker image
+              uses: docker/build-push-action@v6
+              with:
+                  context: .
+                  file: ./release.Dockerfile
+                  platforms: linux/amd64,linux/arm64
+                  push: true
+                  tags: ${{ steps.meta.outputs.tags }}
+                  labels: ${{ steps.meta.outputs.labels }}
+
             - name: Release
               uses: ncipollo/release-action@v1
               with:
@@ -61,8 +103,10 @@ jobs:
                   artifactErrorsFailBuild: true
                   artifacts: |
                       wowsimcli-amd64-linux.zip
+                      wowsimcli-arm64-linux.zip
                       wowsimcli-windows.exe.zip
                       wowsimcata-amd64-darwin.zip
                       wowsimcata-arm64-darwin.zip
                       wowsimcata-amd64-linux.zip
+                      wowsimcata-arm64-linux.zip
                       wowsimcata-windows.exe.zip

.gitignore

@@ -13,7 +13,7 @@ ui/*/*/index.html
 dist
 binary_dist
 sim/web/__debug_bin
-/wowsimcatacli*
+/wowsimcli*
 /wowsimcata*
 
 # temporary files

DEVELOPMENT.md

@@ -0,0 +1,213 @@
+# Local Dev Installation
+
+This project has dependencies on Go >=1.21, protobuf-compiler and the corresponding Go plugins, and node >= 20.
+
+## Ubuntu
+
+Do not use apt to install any dependencies, the versions they install are all too old.
+Script below will curl latest versions and install them.
+
+```sh
+# 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 cata
+
+# 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.39.7/install.sh | bash
+nvm install 20.13.1
+
+# Install the npm package dependencies using node
+npm install
+```
+
+## Docker
+
+Alternatively, install Docker and your workflow will look something like this:
+
+```sh
+git clone https://github.com/wowsims/cata.git
+cd cata
+
+# Build the docker image and install npm dependencies (only need to run these once).
+docker build --tag wowsims-cata .
+docker run --rm -v $(pwd):/cata wowsims-cata npm install
+
+# Now you can run the commands as shown in the Commands sections, preceding everything with, "docker run --rm -it -p 8080:8080 -v $(pwd):/cata wowsims-cata".
+# For convenience, set this as an environment variable:
+CATA_CMD="docker run --rm -it -p 8080:8080 -v $(pwd):/cata wowsims-cata"
+
+#For the watch commands assign this environment variable:
+CATA_WATCH_CMD="docker run --rm -it -p 8080:8080 -p 3333:3333 -p 5173:5173 -e WATCH=1 -v $(pwd):/cata wowsims-cata"
+
+# ... do some coding on the sim ...
+
+# Run tests
+$(echo $CATA_CMD) make test
+
+# ... do some coding on the UI ...
+
+# Host a local site
+$(echo $CATA_CMD) make host
+```
+
+## Windows
+
+If you want to develop on Windows, we recommend setting up a Ubuntu virtual machine (VM) or running Docker using [this guide](https://docs.docker.com/desktop/windows/wsl/ 'https://docs.docker.com/desktop/windows/wsl/') and then following the Ubuntu or Docker instructions, respectively.
+
+## Mac OS
+
+-   Docker is available in OS X as well, so in theory similar instructions should work for the Docker method
+-   You can also use the Ubuntu setup instructions as above to run natively, with a few modifications:
+    -   You may need a different Go installer if `go1.18.3.linux-amd64.tar.gz` is not compatible with your system's architecture; you can do the Go install manually from `https://go.dev/doc/install`.
+    -   OS X uses Homebrew instead of apt, so in order to install protobuf-compiler you’ll instead need to run `brew install protobuf-c` (note the package name is also a little different than in apt). You might need to first update or upgrade brew.
+    -   The provided install script for Node will not included a precompiled binary for OS X, but it’s smart enough to compile one. Be ready for your CPU to melt on running `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash`.
+
+# Commands
+
+We use a makefile for our build system. These commands will usually be all you need while developing for this project:
+
+```sh
+# Installs a pre-commit git hook so that your go code is automatically formatted (if you don't use an IDE that supports that).  If you want to manually format go code you can run make fmt.
+# Also installs `air` to reload the dev servers automatically
+make setup
+
+# Run all the tests. Currently only the backend sim has tests.
+make test
+
+# Update the expected test results. This will need to be run after adding/removing any tests, and also if test results change due to code changes.
+make update-tests
+
+# Host a local version of the UI at http://localhost:8080. Visit it by pointing a browser to
+# http://localhost:8080/cata/YOUR_SPEC_HERE, where YOUR_SPEC_HERE is the directory under ui/ with your custom code.
+# Recompiles the entire client before launching using `make dist/cata`
+make host
+
+# With file-watching so the server auto-restarts and recompiles on Go or TS changes:
+WATCH=1 make host
+
+# Delete all generated files (.pb.go and .ts proto files, and dist/)
+make clean
+
+# Recompiles the ts only for the given spec (e.g. make host_elemental_shaman)
+make host_$spec
+
+# Recompiles the `wowsimcata` server binary and runs it, hosting /dist directory at http://localhost:3333/cata.
+# This is the fastest way to iterate on core go simulator code so you don't have to wait for client rebuilds.
+# To rebuild client for a spec just do 'make $spec' and refresh browser.
+make rundevserver
+
+# With file-watching so the server auto-restarts and recompiles on Go or TS changes:
+WATCH=1 make rundevserver
+
+
+# The same as rundevserver, recompiles  `wowsimcata` binary and runs it on port 3333. Instead of serving content from the dist folder,
+# this command also runs `vite serve` to start the Vite dev server on port 5173 (or similar) and automatically reloads the page on .ts changes in less than a second.
+# This allows for more rapid development, with sub second reloads on TS changes. This combines the benefits of `WATCH=1 make rundevserver` and `WATCH=1 make host`
+# to create something that allows you to work in any part of the code with ease and speed.
+# This might get rolled into `WATCH=1 make rundevserver` at some point.
+WATCH=1 make devmode
+
+# This is just the same as rundevserver currently
+make devmode
+
+# This command recompiles the workers in the /ui/worker folder for easier debugging/development
+# Can be used with or without WATCH command
+make webworkers
+
+# With file watch enabled
+WATCH=1 make webworkers
+
+# Creates the 'wowsimcata' binary that can host the UI and run simulations natively (instead of with wasm).
+# Builds the UI and the compiles it into the binary so that you can host the sim as a server instead of wasm on the client.
+# It does this by first doing make dist/cata and then copying all those files to binary_dist/cata and loading all the files in that directory into its binary on compile.
+make wowsimcata
+
+# Using the --usefs flag will instead of hosting the client built into the binary, it will host whatever code is found in the /dist directory.
+# Use --wasm to host the client with the wasm simulator.
+# The server also disables all caching so that refreshes should pickup any changed files in dist/. The client will still call to the server to run simulations so you can iterate more quickly on client changes.
+# make dist/cata && ./wowsimcata --usefs would rebuild the whole client and host it. (you would have had to run `make devserver` to build the wowsimcata binary first.)
+./wowsimcata --usefs
+
+# Generate code for items. Only necessary if you changed the items generator.
+make items
+```
+
+# Adding a Sim
+
+So you want to make a new sim for your class/spec! The basic steps are as follows:
+
+-   [Create the proto interface between sim and UI.](#create-the-proto-interface-between-sim-and-ui)
+-   [Implement the UI.](#implement-the-ui)
+-   [Implement the sim.](#implement-the-sim)
+-   [Launch the site.](#launch-the-site)
+
+## Create the proto interface between Sim and UI
+
+This project uses [Google Protocol Buffers](https://developers.google.com/protocol-buffers/docs/gotutorial 'https://developers.google.com/protocol-buffers/docs/gotutorial') to pass data between the sim and the UI. TLDR; Describe data structures in .proto files, and the tool can generate code in any programming language. It lets us avoid repeating the same code in our Go and Typescript worlds without losing type safety.
+
+For a new sim, make the following changes:
+
+-   Add a new value to the `Spec` enum in proto/common.proto. **NOTE: The name you give to this enum value is not just a name, it is used in our templating system. This guide will refer to this name as `$SPEC` elsewhere.**
+-   Add a 'proto/YOUR_CLASS.proto' file if it doesn't already exist and add data messages containing all the class/spec-specific information needed to run your sim.
+-   Update the `PlayerOptions.spec` field in `proto/api.proto` to include your shiny new message as an option.
+
+That's it! Now when you run `make` there will be generated .go and .ts code in `sim/core/proto` and `ui/core/proto` respectively. If you aren't familiar with protos, take a quick look at them to see what's happening.
+
+## Implement the UI
+
+The UI and sim can be done in either order, but it is generally recommended to build the UI first because it can help with debugging. The UI is very generalized and it doesn't take much work to build an entire sim UI using our templating system. To use it:
+
+-   Modify `ui/core/proto_utils/utils.ts` to include boilerplate for your `$SPEC` name if it isn't already there.
+-   Create a directory `ui/$SPEC`. So if your Spec enum value was named, `elemental_shaman`, create a directory, `ui/elemental_shaman`.
+-   Copy+paste from another spec's UI code.
+-   Modify all the files for your spec; most of the settings are fairly obvious, if you need anything complex just ask and we can help!
+-   Finally, add a rule to the `makefile` for the new sim site. Just copy from the other site rules already there and change the `$SPEC` names.
+
+No .html is needed, it will be generated based on `ui/index_template.html` and the `$SPEC` name.
+
+When you're ready to try out the site, run `make host` and navigate to `http://localhost:8080/cata/$SPEC`.
+
+## Implement the Sim
+
+This step is where most of the magic happens. A few highlights to start understanding the sim code:
+
+-   `sim/wasm/main.go` This file is the actual main function, for the [.wasm binary](https://webassembly.org/ 'https://webassembly.org/') used by the UI. You shouldn't ever need to touch this, but just know its here.
+-   `sim/core/api.go` This is where the action starts. This file implements the request/response messages defined in `proto/api.proto`.
+-   `sim/core/sim.go` Orchestrates everything. Main event loop is in `Simulation.RunOnce`.
+-   `sim/core/agent.go` An Agent can be thought of as the 'Player', i.e. the person controlling the game. This is the interface you'll be implementing.
+-   `sim/core/character.go` A Character holds all the stats/cooldowns/gear/etc common to any WoW character. Each Agent has a Character that it controls.
+
+Read through the core code and some examples from other classes/specs to get a feel for what's needed. Hopefully `sim/core` already includes what you need, but most classes have at least 1 unique mechanic so you may need to touch `core` as well.
+
+Finally, add your new sim to `RegisterAll()` in `sim/register_all.go`.
+
+Don't forget to write unit tests! Again, look at existing tests for examples. Run them with `make test` when you're ready.
+
+# Launch the site
+
+When everything is ready for release, modify `ui/core/launched_sims.ts` and `ui/index.html` to include the new spec value. This will add the sim to the dropdown menu so anyone can find it from the existing sims. This will also remove the UI warning that the sim is under development. Now tell everyone about your new sim!
+
+# Add your spec to the raid sim
+
+Don't touch the raid sim until the individual sim is ready for launch; anything in the raid sim is publicly accessible. To add your new spec to the raid sim, do the following:
+
+-   Add a reference to the individual sim in `ui/raid/tsconfig.json`. DO NOT FORGET THIS STEP or Typescipt will silently do very bad things.
+-   Import the individual sim's css file from `ui/raid/index.scss`.
+-   Update `ui/raid/presets.ts` to include a constructor factory in the `specSimFactories` variable and add configurations for new Players in the `playerPresets` variable.
+
+# Deployment
+
+Thanks to the workflow defined in `.github/workflows/deploy.yml`, pushes to `master` automatically build and deploy a new site so there's nothing to do here. Sit back and appreciate your new sim!

Dockerfile

@@ -4,7 +4,7 @@ FROM golang:1.21
 
 WORKDIR /cata
 
-RUN rm /bin/sh && ln -s /bin/bash /bin/sh
+SHELL ["/bin/bash", "-c"]
 
 COPY . .
 COPY gitconfig /etc/gitconfig
@@ -16,15 +16,15 @@ RUN apt-get update \
 	&& go install google.golang.org/protobuf/cmd/protoc-gen-go@latest \
 	&& curl -sSfL https://raw.githubusercontent.com/cosmtrek/air/master/install.sh | sh -s -- -b $(shell go env GOPATH)/bin
 
-ENV NODE_VERSION=20.13.1
+ENV NODE_VERSION=20
 ENV NVM_DIR="/root/.nvm"
 
 # Install all Frontend dependencies
 RUN curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash \
-    && . $NVM_DIR/nvm.sh \
-    && nvm install $NODE_VERSION \
-    && nvm alias default $NODE_VERSION \
-    && nvm use default
+	&& . $NVM_DIR/nvm.sh \
+	&& nvm install $NODE_VERSION \
+	&& nvm alias default $NODE_VERSION \
+	&& nvm use default
 
 ENV PATH="/root/.nvm/versions/node/v${NODE_VERSION}/bin/:${PATH}"