Wencan Jiang ¹ · Jiangning Zhang ^1,✉ · Jianbiao Mei ¹ · Jinzhuo Liu ¹ · Yu Yang ¹
Xiaobin Hu ² · Zhucun Xue ¹ · Yong Liu ¹ · Dacheng Tao ³

¹Zhejiang University     ²National University of Singapore     ³Nanyang Technological University

SPIKE is an adaptive dual-controller framework for long-horizon game agents in Stardew Valley. It combines strategic replanning, fast reactive execution, and controller-specific memory to improve task success while reducing unnecessary LLM calls.

SPIKE is designed for long-horizon multimodal agents that must remain goal-directed over many low-level interactions under token and latency constraints.

1. Event-triggered amortized deliberation: Strategic reasoning is reused across stable local segments and reinvoked at visual, progress, repetition, or failure boundaries.
2. Adaptive dual-controller execution: A Strategic Controller handles planning and recovery, while a bounded Reactive Controller performs fast local execution and local override.
3. Controller-specific hierarchical memory: SPIKE separates State-Action Memory Bank retrieval for routine execution from State-Action Knowledge Graph evidence for replanning.
4. Better success-cost trade-off: On StarDojo Lite-100, SPIKE improves success over the strongest baseline while reducing tokens and latency.

• 📷 Introduction
• ✨ Highlight!!!
• 🧭 Summary of Contents
• 🧠 Method Overview
• 🛠️ Installation
  • 1. Prepare the game environment
  • 2. Install the Python runtime
  • 3. Configure local environment
• ⚙️ Configuration
• 📦 Resources
• 🧩 Components
• 🚀 Usage
  • Useful scripts
• ✅ Verification
• 📚 Citation
• 📬 Contact

SPIKE framework. SPIKE uses event-triggered switching to reserve strategic deliberation for discontinuities while reactive execution handles stable local progress.

For Stardew Valley, SMAPI, StarDojoMod, and other game-side setup details, follow the official StarDojo instructions.

git clone https://github.com/Rinke02/SPIKE.git
cd SPIKE
conda create -n Spike python=3.10.9
conda activate Spike
python -m pip install -r requirements.txt
python -m pip install -e ./agent

Create your local environment file:

Copy-Item env/.env.example env/.env

Fill in env/.env with your local STARDEW_APP_PATH and the API key variables referenced by the config you use. Do not commit env/.env; it is ignored by Git.

Set project paths for the current Windows PowerShell session:

.\setup.ps1

This source release includes public templates for Qwen, OpenAI-compatible, and Gemini runs:

agent/conf/qwen_config.json
agent/conf/openai_config.json
agent/conf/gemini_config.json
agent/conf/env_config_stardew.json

The public config files keep model names and embedding settings, but do not contain private keys or service URLs. Fill in base_url, emb_base_url, api_key, emb_api_key, or the corresponding environment variables for your own provider.

The required Stardew task save folders are included under:

env/tasks/saves/save_new
env/tasks/saves/save_farming
env/tasks/saves/save_quests

The default text embedding model is BAAI/bge-base-en-v1.5. When this model is used through sentence-transformers, it can be downloaded automatically on first use or prepared in your local Hugging Face cache in advance. Model files and local cache directories are not included in this repository.

The default visual embedding is local-image-embedding-v1, a deterministic local image feature extractor implemented in agent/cradle/runner/image_embedder.py.

• agent/: core SPIKE agent package, including controller logic, memory modules, Stardew integration, resources, and model configuration templates.
• StardojoMod/: public SMAPI mod source used by the StarDojo-based Stardew Valley runtime.
• env/: Stardew runner code, task suites, save folders, game data, and environment utilities.
• run_lite100_parallel.py: standard Lite-100 parallel benchmark entry point.
• summarize_run_results.py: helper script for summarizing run outputs.
• tests/: minimal checks for the Lite-100 runner and local embedding defaults.

Run from the repository root with Spike activated.

python run_lite100_parallel.py --dry_run --llm_config agent/conf/qwen_config.json --embed_config agent/conf/qwen_config.json

Replace the config paths with the provider templates under agent/conf/ as needed. Remove --dry_run after completing the game-side setup in StarDojo, preparing env/.env, and filling in the required model provider settings.

• run_lite100_parallel.py: standard Lite-100 parallel benchmark.
• summarize_run_results.py: summarize benchmark outputs.
• verify_qwen_no_key.py: check Qwen config behavior without publishing keys.

Runtime output is written under runs/, which is ignored by Git.

You can also check the Lite-100 command generation without launching Stardew Valley:

python run_lite100_parallel.py --dry_run --llm_config agent/conf/qwen_config.json --embed_config agent/conf/qwen_config.json

For an actual game-side smoke test, use a configured env/.env and your own model provider settings, then run a small Lite-100 subset or the full standard Lite-100 entry point.

If you find our work useful, please consider citing us!

@article{jiang2026spike,
  title={SPIKE: An Adaptive Dual Controller Framework for Cost-Efficient Long-Horizon Game Agents},
  author={Wencan Jiang and Jiangning Zhang and Jianbiao Mei and Jinzhuo Liu and Yu Yang and Xiaobin Hu and Zhucun Xue and Yong Liu and Dacheng Tao},
  journal={arXiv preprint arXiv:2605.18636},
  year={2026}
}

For issues or contributions, feel free to open an issue or pull request.