{"id":14959652,"url":"https://github.com/mathiscode/aige","last_synced_at":"2025-10-24T18:30:24.190Z","repository":{"id":209881513,"uuid":"724807381","full_name":"mathiscode/aige","owner":"mathiscode","description":"AI Game Engine","archived":false,"fork":false,"pushed_at":"2024-03-16T17:08:22.000Z","size":454,"stargazers_count":10,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-09-28T13:43:32.313Z","etag":null,"topics":["ai","artificial-intelligence","chatgpt","game-development","game-engine","large-language-models","openai","openai-api"],"latest_commit_sha":null,"homepage":"https://aige.games/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mathiscode.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"mathiscode","custom":"https://imagined.quest"}},"created_at":"2023-11-28T20:45:22.000Z","updated_at":"2024-09-21T21:24:44.000Z","dependencies_parsed_at":"2023-12-15T19:54:53.591Z","dependency_job_id":"239c752b-c7b5-4ce5-8505-d3fac86feb0d","html_url":"https://github.com/mathiscode/aige","commit_stats":{"total_commits":67,"total_committers":2,"mean_commits":33.5,"dds":"0.014925373134328401","last_synced_commit":"2d29e14b15ddbe82f2932ca71af56eb902dddb1b"},"previous_names":["mathiscode/aige"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mathiscode%2Faige","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mathiscode%2Faige/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mathiscode%2Faige/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mathiscode%2Faige/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mathiscode","download_url":"https://codeload.github.com/mathiscode/aige/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219868210,"owners_count":16555876,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","artificial-intelligence","chatgpt","game-development","game-engine","large-language-models","openai","openai-api"],"created_at":"2024-09-24T13:20:30.052Z","updated_at":"2025-10-24T18:30:23.801Z","avatar_url":"https://github.com/mathiscode.png","language":"TypeScript","funding_links":["https://github.com/sponsors/mathiscode","https://imagined.quest"],"categories":[],"sub_categories":[],"readme":"\u003c!-- markdown-lint-disable MD014 --\u003e\n\n# AIGE: The AI Game Engine\n\nAIGE is a Node.js library that utilizes the OpenAI API to generate text-based games in any universe.\n\nDevelopers can integrate AIGE into their own projects to create games that are unique every time.\n\nAI-based games can go off the rails and not make sense sometimes, but that's part of the fun!\n\nMade with ❤️ by [Jay Mathis](https://github.com/mathiscode)\n\nPlease consider [becoming a sponsor](https://github.com/sponsors/mathiscode) or buying tokens on [Imagined.Quest](https://imagined.quest) if you appreciate my work.\n\n---\n\n[![View Docs](https://img.shields.io/badge/view-docs-blue?style=for-the-badge)](https://aige.games)\n[![Made with TypeScript](https://img.shields.io/badge/made_with-typescript-blue?style=for-the-badge)](https://www.typescriptlang.org)\n\n[![NPM](https://img.shields.io/npm/dw/%40aige%2Fcore)](https://www.npmjs.com/package/@aige/core)\n[![Version](https://img.shields.io/github/package-json/v/mathiscode/aige?color=success)](https://www.npmjs.com/package/@aige/core)\n[![CircleCI](https://img.shields.io/circleci/build/github/mathiscode/aige/master)](https://app.circleci.com/pipelines/github/mathiscode/aige)\n[![Last Commit](https://img.shields.io/github/last-commit/mathiscode/aige.svg)](https://github.com/mathiscode/aige/commit/master)\n[![Open issues](https://img.shields.io/github/issues/mathiscode/aige.svg)](https://github.com/mathiscode/aige/issues)\n[![Closed issues](https://img.shields.io/github/issues-closed/mathiscode/aige.svg)](https://github.com/mathiscode/aige/issues?q=is%3Aissue+is%3Aclosed)\n\n[![Sponsors](https://img.shields.io/github/sponsors/mathiscode?color=red)](https://github.com/sponsors/mathiscode)\n[![Contributors](https://img.shields.io/github/contributors/mathiscode/aige?color=yellow)](https://github.com/mathiscode/aige/graphs/contributors)\n[![GitHub license](https://img.shields.io/badge/license-MIT-blue)](https://github.com/mathiscode/aige/blob/master/LICENSE.md)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-blue.svg)](https://github.com/mathiscode/aige/compare)\n\n[![Followers](https://img.shields.io/github/followers/mathiscode?style=social)](https://github.com/mathiscode)\n[![Watchers](https://img.shields.io/github/watchers/mathiscode/aige?style=social)](https://github.com/mathiscode/aige)\n[![Stars](https://img.shields.io/github/stars/mathiscode/aige?style=social)](https://github.com/mathiscode/aige)\n\n---\n\n## Features \u003c!-- omit in toc --\u003e\n\n- 🎮 Create games in any universe\n- 🗨️ Chat with any character\n- 🎨 Generate images for various game elements using DALL-E\n- 👨‍💻 An \"action\" in the game can be any prompt, allowing virtually infinite possibilities\n- 📝 The game will suggest actions for the player to choose from\n- 🧠 Manage game state with a simple API\n- 📦 Export and import games as JSON\n- 🚨 Track game events with event listeners\n- 🧰 Track stats, scene, inventory, characters, abilities, quests, and more\n- 🤖 Powered by [OpenAI API](https://platform.openai.com/docs/overview) (planned support for additional LLMs)\n\n---\n\n[![asciicast](https://asciinema.org/a/624036.svg)](https://asciinema.org/a/624036)\n\n---\n\n## Table of Contents \u003c!-- omit in toc --\u003e\n\n- [AIGE: The AI Game Engine](#aige-the-ai-game-engine)\n  - [CLI](#cli)\n  - [Installation](#installation)\n  - [Documentation](#documentation)\n  - [Simple Example](#simple-example)\n  - [Full Example](#full-example)\n  - [Development](#development)\n  - [Notes](#notes)\n\n---\n\n## CLI\n\nJust want to play some games? Try the CLI!\n\n```sh\nOPENAI_API_KEY=sk-youropenaikey npx @aige/core@latest\n```\n\n```text\nAIGE vX.Y.Z\nhttps://aige.games\nType \"help\" for a list of commands\n? 🎮 create\n```\n\n## Installation\n\n```sh\nnpm install @aige/core # or your package manager's equivalent (pnpm recommended)\n```\n\n## Documentation\n\n[View the docs on aige.games](https://aige.games)\n\n## Simple Example\n\n```js\nimport fs from 'node:fs'\nimport { Game, GameEvent } from '@aige/core'\n\nconst game = new Game({ clientOptions: { apiKey: 'sk-openaikey' } })\nawait game.init()\nconsole.log(`${game.data.scene_emoji} ${game.scene}`)\n\nconst action = game.data.actions[0]\nconsole.log(`Performing action: ${action}`)\nawait game.action(action)\nconsole.log(`${game.data.scene_emoji} ${game.scene}`)\n\nawait game.action('Attack the nearest enemy')\nconsole.log(game.inspect())\n\ngame.on(GameEvent.chat, ({ character, dialog }) =\u003e console.log(`${character.name}: ${dialog}`))\nawait game.chat(game.data.characters[0], 'Hello!')\n\nconst images = await game.images({ player: true, scene: true })\nconsole.dir(images)\n\nfs.writeFileSync('./game.json', JSON.stringify(game.export()))\n```\n\n## Full Example\n\n```js\nimport fs from 'node:fs'\nimport { Game, GameEvent } from '@aige/core'\n\n// If using the environment variable, you can omit the apiKey option entirely\nconst OPENAI_API_KEY = process.env.OPENAI_API_KEY || 'your-openai-api-key'\n\n// completely random game\nconst game1 = new Game({ clientOptions: { apiKey: OPENAI_API_KEY } }) \n\n// import a game from a JSON export\nconst game2 = new Game({ clientOptions: { apiKey: OPENAI_API_KEY } })\ngame2.import(JSON.parse(fs.readFileSync('./game.json', 'utf8')))\n\n// specify game options\nconst game3 = new Game({\n  clientOptions: { apiKey: OPENAI_API_KEY },\n  universe: 'Warhammer 40K',\n  playerName: 'Konrad Curze',\n  playerClass: 'Primarch'\n})\n\n// change the way the game is created (can also be specified in Game constructor)\ngame1.options.prompts.create = 'Create game but all text in every argument should be uppercase'\ngame1.options.prompts.name = 'Get the player name but make it hard to pronounce'\ngame1.options.prompts.class = 'Get the player class but make it all numbers'\n\n// Initializing is only necessary for new games, not imported games\nawait game1.init()\nawait game3.init()\n\n// Game states:\nconsole.log(game1.inspect())\nconsole.log(game2.inspect())\nconsole.log(game3.inspect())\n\n// Perform actions:\nconst action = game1.data.actions[Math.floor(Math.random() * game1.data.actions.length)]\nawait game1.action(action) // Use a suggested action\nawait game2.action('Explore the area')\nawait game3.action('Do Night Haunter things')\n\n// Manually set a game value:\ngame1.set('health', 10000)\ngame2.set('abilities[0].name', 'Renamed Ability')\ngame3.set('characters[0].hostile', true)\n\n// Add event listeners:\ngame1.on(GameEvent.gain, ({ attribute, amount }) =\u003e console.log(`Gained ${amount} ${attribute}`))\ngame2.on(GameEvent.loss, ({ attribute, amount }) =\u003e console.log(`Lost ${amount} ${attribute}`))\ngame3.on(GameEvent.chat, ({ character, dialog }) =\u003e console.log(`${character.name}: ${dialog}`))\n\n// Chat with a character:\nawait game3.chat(game3.data.characters[0], 'Stop doing crime!')\n\n// Generate images:\nconst item = game3.data.inventory[0]\nconst ability = game3.data.abilities[0]\n\n// You can provide any combination of the following options to the images method:\nconst images = await game3.images({\n  player: true,\n  scene: true, \n  character,\n  ability,\n  item\n}, {\n  user: 'user-id', // optional\n  size: '512x512' // 256x256 | 512x512 (default) | 1024x1024 | 1792x1024 | 1024x1792\n  style: 'vivid' // vivid (default) | natural\n  quality: 'hd' // hd (default) | standard\n  model: 'dall-e-2' // dall-e-2 (default) | dall-e-3\n  response_format: 'url' // url (default) | b64_json\n})\n\nconsole.log(images)\n// { player?: 'https://...', scene?: 'https://...',\n// character?: 'https://...', ability?: 'https://...', item?: 'https://...' }\n\n// Save the game state to a JSON file\nfs.writeFileSync('./game1.json', JSON.stringify(game1.export(), null, 2))\nfs.writeFileSync('./game2.json', JSON.stringify(game2.export(), null, 2))\nfs.writeFileSync('./game3.json', JSON.stringify(game3.export(), null, 2))\n```\n\nSee [tests](https://github.com/mathiscode/aige/tree/master/test) and [cli.ts](https://github.com/mathiscode/aige/tree/master/src/cli.ts) for more examples on how to use the library.\n\n## Development\n\nRun the following commands:\n\n```sh\ngit clone https://github.com/mathiscode/aige.git\ncd aige\necho \"OPENAI_API_KEY=sk-youropenaikey\" \u003e .env\npnpm install\npnpm test\n```\n\nAll scripts:\n\n```sh\npnpm test # run tests one time\npnpm test:watch # run tests and watch for changes\npnpm test:coverage # run tests and generate a coverage report\npnpm build # build the library and docs\npnpm build:library # build the library\npnpm build:docs # build the docs\npnpm build:docs:watch # build the docs and watch for changes\npnpm dev:cli # run the CLI with the Node.js debugger attached\n```\n\nThere is a `launch.json` file included for debugging in VSCode.\n\n## Notes\n\nOpenAI's API can sometimes be slow to respond with larger schemas, and the `create` and `update` tools have fairly heavy schemas. As time goes on, both OpenAI and AIGE will improve and become faster.\n\nOptimizations Coming:\n\n- Allow custom schemas to reduce token usage by pruning unused data, and allowing flexibility in game structure\n- Chunk the creation and action calls into smaller pieces to reduce token usage per call, giving faster responses\n\nThe default models are `gpt-3.5-turbo-1106` and `dall-e-2`. You can set the models in the [GameClientOptions](https://aige.games/interfaces/Core.GameClientOptions.html) to use others. Creating a game and performing an action uses ~2000-3000 tokens.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmathiscode%2Faige","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmathiscode%2Faige","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmathiscode%2Faige/lists"}