Adjutant Mod API v0 (preview) ============================== Written for AI coding agents and modders. Adjutant is a voice-commanded AI officer for strategy games. The player gives orders by voice, in their own words. Adjutant listens, decides what the units should do, sends your game structured commands, and answers the player out loud. A mod for an existing game, or your own game, is the bridge: it tells Adjutant what is on the battlefield and executes the commands it receives. Status: PREVIEW. The Adjutant app for Windows is not released yet. Names and fields may change before release. Download: https://adjutantgame.com/developers/#download (until release it says "coming soon" and offers the waitlist). ------------------------------------------------------------ 1. What the player runs ------------------------------------------------------------ - The Adjutant app on the same Windows PC as the game. The player turns on "Host AI" in its launcher. - In Host AI mode the app thinks for the adjutant on this PC. It uses one of these: - a free local model on an NVIDIA GPU with 8 GB or more; - an AI API of the player's choice (any OpenAI-compatible API key). (Host AI can also use a Claude or ChatGPT subscription, at the player's own risk: subscription terms are the vendor's and may not allow it.) - The app does the listening (microphone, push-to-talk), the thinking and the voice. Your mod does not handle audio input, models or keys. ------------------------------------------------------------ 2. Find Adjutant ------------------------------------------------------------ GET http://127.0.0.1:18080/ping -> 200 {"ok": true, ...} Adjutant is running. -> no answer Adjutant is not running. Ask the player to start it and turn on Host AI. Retry every few seconds; never block the game. Only 127.0.0.1 is accepted. Do not send a Host header other than 127.0.0.1 or localhost. ------------------------------------------------------------ 3. Connect ------------------------------------------------------------ WebSocket: ws://127.0.0.1:18080/mod Every message is one JSON object with a "type" field. Text frames, UTF-8. -> hello (first message, once) { "type": "hello", "api": "adjutant-mod/0", "game": "my-game-name", // short id of the game or mod "lang": "en", // language the player speaks: en ru de es pt zh ja "units_doc": "One line about how units work in this game (optional).", "commands": [ ... ] // optional: your own commands, see section 6 } <- welcome { "type": "welcome", "session": "s-...", "api": "adjutant-mod/0", "commands": ["move", "attack", "hold", "...yours"] } <- error (any time) { "type": "error", "code": "bad_message", "message": "human-readable reason" } ------------------------------------------------------------ 4. Describe the battlefield ------------------------------------------------------------ -> state (send when a battle starts, then about once a second while it runs; always the full picture) { "type": "state", "t": 12.5, // seconds since the battle started "map": { "w": 2000, "h": 1500 }, // map size in your game units; x to the right, y down "own": [ // the player's units { "id": "R1", "kind": "spearmen", "x": 640, "y": 1210, "facing": 0, "strength": 0.9, // 0..1 of full strength "status": "idle", // idle | moving | fighting | routing | ... "name": "1st Spears" } // optional display name ], "enemy": [ // only the enemy units the player can see { "id": "E4", "kind": "cavalry", "x": 1500, "y": 300, "strength": 1, "status": "moving" } ], "places": [ // named terrain the player may mention { "name": "Centre Hill", "kind": "hill", "x": 780, "y": 700, "r": 90 }, { "name": "West Wood", "kind": "wood", "x": 290, "y": 610, "r": 120 } ] } -> event (optional: things the adjutant should know about right away) { "type": "event", "kind": "unit_routed", "units": ["R3"], "text": "The 3rd Archers are fleeing." } -> text (optional: a typed order, if your game has a chat box) { "type": "text", "text": "archers behind the spears" } Voice orders need nothing from your mod: the player holds the push-to-talk key and speaks. ------------------------------------------------------------ 5. Receive orders ------------------------------------------------------------ <- commands { "type": "commands", "id": "c-17", "list": [ { "cmd": "move", "units": ["R1", "R2"], "to": { "x": 780, "y": 700 } }, { "cmd": "attack", "units": ["C1"], "target": "E4" }, { "cmd": "hold", "units": ["R3"] } ] } Built-in commands: move {units, to:{x,y}, path?:[{x,y},...]} go there, following the path if given attack {units, target} engage that enemy unit id hold {units} stop and hold the current position Your own commands are added through "commands" in hello (section 6). -> result (reply to every commands message) { "type": "result", "id": "c-17", "ok": [0, 2], "failed": [ { "i": 1, "reason": "C1 is routing" } ] } "i" is the index in "list". The adjutant tells the player what failed, and why. <- say (the adjutant speaks) { "type": "say", "text": "Spears up Centre Hill, my lord.", "mood": "calm" } The Adjutant app plays the voice itself. Show the text in your game if you can (a subtitle or a log line). ------------------------------------------------------------ 6. Your own commands ------------------------------------------------------------ In hello, "commands" lists extra actions your game supports. Each has a name, a one-line doc and JSON Schema params: { "name": "form", "doc": "Change a unit's formation.", "params": { "type": "object", "properties": { "units": { "type": "array", "items": { "type": "string" } }, "shape": { "enum": ["line", "square", "wedge", "loose"] } }, "required": ["units", "shape"] } } Adjutant only sends a command that is valid against its schema. ------------------------------------------------------------ 7. Lifecycle ------------------------------------------------------------ - Connect when the battle screen opens, then send hello and the first state. - Keep sending state while the battle runs. - -> {"type": "end", "result": "victory" | "defeat" | "draw"} when the battle ends. Keep the socket open for the next battle. - If the socket drops, reconnect with a new hello. Keep the game playable without Adjutant. ------------------------------------------------------------ 8. A minimal mod (pseudocode) ------------------------------------------------------------ ws = connect("ws://127.0.0.1:18080/mod") ws.send({type:"hello", api:"adjutant-mod/0", game:"my-game", lang:"en"}) every 1 s during battle: ws.send({type:"state", t, map, own, enemy, places}) on message m: if m.type == "commands": ok, failed = [], [] for i, c in m.list: try execute(c); ok.add(i) except e: failed.add({i, reason: e}) ws.send({type:"result", id:m.id, ok, failed}) if m.type == "say": show_subtitle(m.text) ------------------------------------------------------------ 9. Licence ------------------------------------------------------------ - Personal and non-commercial use, including free mods: open licence. - Bundling Adjutant into a game that is sold: contact us at https://adjutantgame.com/developers/#commercial