Build and share

Use --target web for browsers and --target native for desktop games. The supported game runtimes are:

Scroll to see all columns.

Every supported development machine can package any listed game platform. The CLI compiles one WASM cartridge and downloads the destination's checksum-verified host. Players need neither the CLI nor TinyGo.

Publish a browser game

From your project's folder:

karty build --target web
karty serve dist/web --addr 127.0.0.1:8080

Open http://127.0.0.1:8080/ and test the built game. Upload the whole dist/web/ directory to a static host, including content/ when present. Use HTTP hosting; opening index.html directly is not the preview workflow.

Build and run a native game

Build for your current machine, then launch it on Linux or macOS:

karty build --target native
cd dist/native
./karty-host --cartridge game.kart

On Windows, run .\karty-host.exe --cartridge game.kart in PowerShell from dist/native/. The build summary prints the command for your machine.

To package another platform, run these from the project root:

karty build --target native --platform windows-arm64
karty build --target native --platform linux-arm64
karty build --target native --platform darwin-arm64

Explicit platforms use separate folders, such as dist/native/windows-arm64/. On the destination Windows machine, open that folder and run .\karty-host.exe --cartridge game.kart.

Keep a LICENSES/ folder in your project containing Karty's runtime and library notices from the release downloads, plus notices required by your own assets and dependencies. Commit this folder with your source. Copy it into each distribution before sharing:

cp -R LICENSES dist/web/
cp -R LICENSES dist/native/

For a named native platform, use its output folder instead, such as cp -R LICENSES dist/native/windows-arm64/. Share the whole selected folder, including its content/ and LICENSES/ files. Browser and desktop use the same source. Test each platform you ship.

Share reusable code, prefabs and UI

To publish your own package, follow Write and publish a package.

Install published code and assets from the Plugins catalog by name:

karty package import fps-kit@0.0.1

Omit the version to select the latest stable release. Commit the resolved archive URL and SHA-256 in karty.toml; future builds restore that same pin. Use karty package import --replace fps-kit for an explicit update.

For a package folder containing karty-package.toml, export a local archive:

karty package export --output placeholder-kit-0.1.0.kpkg ../placeholder-kit

From a consuming game, import the archive using the name in its package manifest:

karty package import placeholder-kit-0.1.0.kpkg

Commit the referenced archive and updated karty.toml/go.mod; the CLI restores its checked contents under ignored .karty/packages/. To edit the package live, use karty package import --replace ../placeholder-kit instead. karty dev watches that working folder, including outside the game. The current package CLI supports Go behavior, static/nested prefabs, PNG world materials and KartUI components/layouts with images, fonts and theme defaults; use a CLI build containing that feature. UI exports compile against the consuming game and keep normal typed props/callbacks. The game owns state and lifecycle.

Build in CI

Commit karty.toml, go.mod, source code, and source assets. Include go.sum when your dependencies create it. The runner recreates .karty/ and dist/; do not commit those folders.

Save this as .github/workflows/game.yml in your game project. It builds a browser game and a Windows ARM64 distribution on Linux, then uploads each folder for review. Include the LICENSES/ folder described above so the artifacts contain the required notices. The workflow installs the latest CLI. No private engine checkout or credentials are needed.

name: Build game
on: [push, pull_request]
permissions:
  contents: read
jobs:
  build:
    runs-on: ubuntu-24.04
    env:
      GOEXPERIMENT: simd
      GOWORK: "off"
    steps:
      - uses: actions/checkout@v7.0.1
        with:
          persist-credentials: false
      - uses: actions/setup-go@v7.0.0
        with:
          go-version: "1.27.3"
          cache: false
      - name: Install Karty
        run: |
          go install github.com/karty-game/karty/cmd/karty@latest
          echo "$(go env GOPATH)/bin" >> "$GITHUB_PATH"
      - name: Prepare material generation
        run: |
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends libegl1 libgl1-mesa-dri
      - name: Build distributions
        run: |
          karty build --target web
          karty build --target native --platform windows-arm64
          cp -R LICENSES dist/web/
          cp -R LICENSES dist/native/windows-arm64/
      - uses: actions/upload-artifact@v7.0.0
        with:
          name: game-web
          path: dist/web/
          if-no-files-found: error
      - uses: actions/upload-artifact@v7.0.0
        with:
          name: game-windows-arm64
          path: dist/native/windows-arm64/
          if-no-files-found: error

Change the native --platform, artifact name, and artifact path together. For Linux or macOS artifacts, upload a tar archive of the folder to preserve the host's executable permission. For offline lighting, add karty render bake before the builds. Material generation uses Mesa software OpenGL when the runner has no GPU; the libraries above provide its EGL backend. Packaging a game in CI does not test its graphics, input, or sound on the destination platform.

Choose a sample to extend:

• The Hangar: a portal loop, detailed materials, baked lights, and a torch.
• Orbital flight deck: menus and reusable KartUI components.
• Media lab: sound, music, and video.