gitwtfhub

wtf is ai-game-framework?

asti-z/ai-game-framework — explained in plain English

Analysis updated 2026-05-18

24PythonAudience · developerLicenseSetup · easy

TL;DR

A Python lobby framework that lets multiple text based AI games share energy, gold, and trophies by dropping in a folder with a simple cmd(text) function.

Mindmap

mindmap
  root((ai-game-framework))
    What it does
      Lobby for text-based AI games
      Shares gold energy trophies
      Routes commands to active game
    How to add a game
      manifest.json metadata
      engine.py with cmd function
      No base class needed
    Known limits
      Experimental prototype
      Listed unfixed bugs
      Save isolation incomplete
    Related project
      three-daily full example
      Fishing stock bracelet games

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Why would anyone build with this?

REASON 1

Build several small text-based AI games that share a common economy of gold and energy

REASON 2

Plug an existing text game into a shared lobby by writing one cmd(text) function

REASON 3

Prototype cross-game achievements and trophy systems

REASON 4

Study a manifest-driven plugin discovery pattern for game or tool frameworks

What's in the stack?

Python

How it stacks up

asti-z/ai-game-framework0311119/free_registertool18597990650-lab/multi-agent-game
Stars242424
LanguagePythonPythonPython
Setup difficultyeasyhardmoderate
Complexity4/53/5
Audiencedeveloperdeveloperdeveloper

Figures from each repo's GitHub metadata at analysis time.

How do you spin it up?

Difficulty · easy Time to first run · 30min

Author documents unfixed bugs, including command name collisions and incomplete save file isolation between games.

Wtf does this do

ai-game-framework, called arcade in its own README, is a small Python framework for building text based simulator games meant to be played by AI agents rather than humans. Instead of building one game, it acts as a lobby that lets several separate text games share things like gold, energy, and trophies, while routing whatever the player types to whichever game is currently active. To plug a game into arcade, you drop a folder into a games directory containing just two files: a manifest.json describing the game's name, icon, and how much energy each action costs, and an engine.py file that exposes a single cmd(text) function which takes a text command and returns a text response. There is no base class to inherit and nothing else to register, arcade discovers games automatically from that folder structure. The lobby itself handles a handful of commands, like listing installed games, switching between them, checking your overall status, and viewing or editing configuration values such as energy costs and starting gold. Energy is spent per action according to each game's settings, regenerates slowly over time, and some commands can be marked free. Trophies can be defined per game or shared across all games, with support for trophies that have multiple levels. The author is direct about the project's current state: it is an early experimental prototype, and a companion README section lists several known bugs, such as a lobby command accidentally overriding a game's own command with the same name, and save files not actually being isolated between games as intended, discovered during third party testing. The author explains these are not being fixed here because the lessons learned were carried into a separate, more complete implementation called three-daily, which is the actual playable example of this framework in action, combining a fishing game, a stock trading game, and a bead bracelet game that share energy, gold, and trophies. The license is PolyForm Noncommercial 1.0.0, allowing personal, educational, and research use but not commercial use.

Yoink these prompts

Prompt 1
Help me create a new game folder for ai-game-framework using the example_game template.
Prompt 2
Explain how ai-game-framework routes commands between the lobby and the active game.
Prompt 3
Walk me through the manifest.json format used by ai-game-framework to declare energy costs and trophies.
Prompt 4
Summarize the known bugs the author lists in ai-game-framework and why they were not fixed.

Frequently asked questions

wtf is ai-game-framework?

A Python lobby framework that lets multiple text based AI games share energy, gold, and trophies by dropping in a folder with a simple cmd(text) function.

What language is ai-game-framework written in?

Mainly Python. The stack also includes Python.

How hard is ai-game-framework to set up?

Setup difficulty is rated easy, with roughly 30min to a first successful run.

Who is ai-game-framework for?

Mainly developer.

View the repo → Decode another repo

This repo across BitVibe Labs

Don't trust strangers blindly. Verify against the repo.