agent-dst

agent-dst is a hybrid repository for experimenting with LLM-agent gameplay in Don't Starve Together. It combines:

1. a DST client-bound mod scaffold that can expose structured, text-first observations and actions
2. a Rust workspace for the external bridge and cli
3. legacy worldgen research kept only as reference material from the original dst-vast-world template

Current direction

The short-term goal is to evolve this repo into a text-native agent interface for DST:

• DST mod: world observation, action execution, session/runtime hooks
• Rust bridge: external control plane and polling loop
• Rust CLI: human/agent-facing command surface

The bridge poll interval is designed to be configurable, with an initial default of 100ms.

First implemented surfaces

The repository now includes a real first-version control plane:

• a Rust HTTP bridge with session, state, history, command, and cancel endpoints
• a Rust CLI that auto-resolves the current client-player session, renders compact text status, and groups actions into subcommands
• a Lua runtime that can bind the local real player on the client, publish snapshots outward, and execute bridge commands through vanilla controller APIs

Current client execution scope:

• wait
• move_to (prediction-aware walking through PlayerController)
• craft
• inspect_entity
• say
• chat
• pickup
• work
• equip
• unequip
• use
• eat
• drop
• give
• fuel
• open_container
• close_container
• store
• take_container_item

The legacy agent_dst_actor server pawn is still kept in-tree as a fallback/reference path, but it is no longer the default runtime mode.

Repository layout

Path	Purpose
modinfo.lua, modmain.lua, modworldgenmain.lua	DST mod entrypoints and config
scripts/	Lua modules; includes inactive legacy worldgen reference code
dev-scripts/	DST helper scripts for local reference setup and mod installation
crates/agent-dst-bridge/	Rust bridge binary
crates/agent-dst/	Rust CLI binary
nix/	Shared Rust/Nix packaging, checks, and dev shell configuration
docs/	DST mod docs plus Rust workspace guidance

Development

nix develop

Inside the dev shell you can use both stacks:

cargo fmt
cargo test
nix flake check

For DST setup and manual mod installation, including the local DST_RUNTIME_PATH branch selection and runtime log helpers, see docs/dev-guide.md.

To run the bridge and CLI locally:

cargo run -p agent-dst-bridge
cargo run -p agent-dst -- status
cargo run -p agent-dst -- move to "(-502.5,372.1)"
cargo run -p agent-dst -- craft axe
cargo run -p agent-dst -- inspect evergreen
cargo run -p agent-dst -- interact pickup flower
cargo run -p agent-dst -- inventory equip axe
cargo run -p agent-dst -- inventory eat berries
cargo run -p agent-dst -- inventory drop petals
cargo run -p agent-dst -- interact apply lantern --item lightbulb
cargo run -p agent-dst -- interact give pigman --item berries
cargo run -p agent-dst -- interact fuel campfire --item log
cargo run -p agent-dst -- container open treasurechest
cargo run -p agent-dst -- container store treasurechest --item log
cargo run -p agent-dst -- say "hello nearby"
cargo run -p agent-dst -- chat "hello everyone"

Documentation

Document	Content
docs/runtime-design.md	Runtime architecture, HTTP API, session model, first-version scope
docs/dev-guide.md	DST setup, local reference files, mod installation, Rust/Nix workflow
docs/cli-reference.md	Full CLI command reference, supported actions, and current gaps
docs/architecture.md	Legacy worldgen analysis retained from the original template

Legacy worldgen reference

This repository started from a worldgen-focused DST mod. That code and analysis are intentionally preserved as reference material, but agent-dst no longer loads the world-size hooks at runtime so it can coexist with dedicated worldgen mods.