foundry-tools

module

v0.0.1 Latest Latest Go to latest Published: Jul 2, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/cafecito-games/foundry-tools

Links

Open Source Insights

README ¶

Foundry Tools

Tooling for Foundry Engine projects.

This repository ships package management and protobuf code generation for Foundry Script:

anvil: direct CLI for Foundry project tooling.
protoc-gen-foundryscript: protoc and Buf plugin.

Generated .pb.fs files use Foundry Script namespaces, traits, generics, nullable types, and typed collections. Public generated APIs avoid Variant unless a Foundry Engine API requires it.

Install

Homebrew:

brew install --cask cafecito-games/tap/foundry-tools

Go:

go install github.com/cafecito-games/foundry-tools/cmd/anvil@latest
go install github.com/cafecito-games/foundry-tools/cmd/protoc-gen-foundryscript@latest

Direct CLI

anvil proto generate -I proto -o foundry/generated proto/player.proto

Package Manager

anvil pkg installs Foundry packages declared in packages.toml into a project's addons/ directory and writes packages.lock for reproducible installs.

Project layout:

game/
  project.foundry
  packages.toml
  packages.lock
  addons/
    my_package/

Create a starter manifest next to project.foundry:

anvil pkg init

Add and install a package:

anvil pkg add --name my_package \
  --source git \
  --url https://github.com/org/my_package.git \
  --version v1.0.0 \
  --source-path addons/my_package

Install, update, remove, and list packages:

anvil pkg install
anvil pkg update
anvil pkg update my_package
anvil pkg remove my_package
anvil pkg list

Supported sources:

git: clone a Git repository at a tag, branch, or commit SHA.
github-release: download one asset from a GitHub release.
archive: download a direct HTTP(S) zip, .tar.gz, or .tgz archive.

Example packages.toml:

[packages.my_package]
source = "git"
url = "https://github.com/org/my_package.git"
version = "v1.0.0"
source_path = "addons/my_package"
install_as = "my_package"
exclude = ["editor_only"]

Commit both packages.toml and packages.lock. anvil pkg install honors existing lock pins when the manifest entry has not changed; anvil pkg update intentionally re-resolves pins.

protoc

protoc \
  --plugin=protoc-gen-foundryscript="$(which protoc-gen-foundryscript)" \
  --foundryscript_out=foundry/generated \
  -I proto \
  proto/player.proto

Buf

version: v2
plugins:
  - local: protoc-gen-foundryscript
    out: foundry/generated

Run:

buf generate

Foundry Options Proto

Print the custom options schema:

anvil proto print-options-proto > proto/foundrytools/options.proto
protoc-gen-foundryscript --print-options-proto > proto/foundrytools/options.proto

Supported file options:

option (foundrytools.namespace) = "cafecito.game.v1";
option (foundrytools.type_prefix) = "Game";
option (foundrytools.emit_runtime) = true;

Development

task              # local CI without Foundry
task build        # build binaries into ./bin
task test         # Go tests with -race
task integration  # protoc and Buf integration tests
task lint         # golangci-lint

Foundry checks require a recent Foundry editor build:

FOUNDRY_BIN="$HOME/.foundry/bin/foundry.macos.editor.dev.arm64" task foundry:test

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
anvil command Package main provides the anvil command.	Package main provides the anvil command.
protoc-gen-foundryscript command Package main provides the protoc-gen-foundryscript plugin command.	Package main provides the protoc-gen-foundryscript plugin command.
internal
anvil Package anvil defines the root command shell for the anvil binary.	Package anvil defines the root command shell for the anvil binary.
foundrytest Package foundrytest contains helpers for locating Foundry test binaries.	Package foundrytest contains helpers for locating Foundry test binaries.
foundrytoolspb Package foundrytoolspb contains generated Go bindings and embedded schema bytes for foundrytools/options.proto.	Package foundrytoolspb contains generated Go bindings and embedded schema bytes for foundrytools/options.proto.
packagemanager Package packagemanager exposes Foundry package-manager operations used by the anvil CLI.	Package packagemanager exposes Foundry package-manager operations used by the anvil CLI.
packagemanager/internal/installer Package installer copies fetched package sources into a Foundry project's addons directory.	Package installer copies fetched package sources into a Foundry project's addons directory.
packagemanager/internal/lockfile Package lockfile reads and writes reproducible package pins.	Package lockfile reads and writes reproducible package pins.
packagemanager/internal/manifest Package manifest reads, writes, and validates packages.toml.	Package manifest reads, writes, and validates packages.toml.
packagemanager/internal/output Package output defines package-manager error classes and exit codes.	Package output defines package-manager error classes and exit codes.
packagemanager/internal/project Package project discovers Foundry project roots and package-manager paths.	Package project discovers Foundry project roots and package-manager paths.
packagemanager/internal/source Package source fetches package sources from Git, GitHub releases, and archives.	Package source fetches package sources from Git, GitHub releases, and archives.
plugin Package plugin implements the protoc CodeGeneratorRequest protocol.	Package plugin implements the protoc CodeGeneratorRequest protocol.
proto Package proto exposes protobuf-to-Foundry-Script generation operations.	Package proto exposes protobuf-to-Foundry-Script generation operations.
proto/internal/ast Package protoast defines proto AST node types.	Package protoast defines proto AST node types.
proto/internal/desc Package protodesc converts protoc descriptors to the proto AST.	Package protodesc converts protoc descriptors to the proto AST.
proto/internal/foundryscript/ast Package fsast renders a small Foundry Script AST used by code generation.	Package fsast renders a small Foundry Script AST used by code generation.
proto/internal/foundryscript/generator Package fsgenerator generates Foundry Script protobuf bindings.	Package fsgenerator generates Foundry Script protobuf bindings.
proto/internal/foundryscript/types Package fstypes models Foundry Script type annotations.	Package fstypes models Foundry Script type annotations.
proto/internal/parser Package protoparse tokenizes and parses .proto source files.	Package protoparse tokenizes and parses .proto source files.
proto/internal/validate Package protovalidate performs semantic validation on a proto AST.	Package protovalidate performs semantic validation on a proto AST.
runtime Package runtime embeds the typed Foundry Script protobuf runtime.	Package runtime embeds the typed Foundry Script protobuf runtime.
version Package version defines the anvil version command.	Package version defines the anvil version command.