{"id":48110693,"url":"https://github.com/dimitarbez/ai-build","last_synced_at":"2026-04-04T16:05:54.664Z","repository":{"id":335154755,"uuid":"1144403197","full_name":"dimitarbez/ai-build","owner":"dimitarbez","description":"A Minecraft Paper plugin that uses AI to help build structures in-game. Players can describe what they want to build, and the AI will generate the structure using Minecraft blocks.","archived":false,"fork":false,"pushed_at":"2026-01-28T19:25:05.000Z","size":33,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-29T09:46:30.773Z","etag":null,"topics":["minecraft","minecraft-plugin","paper-mc"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dimitarbez.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-28T16:51:34.000Z","updated_at":"2026-01-28T19:25:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dimitarbez/ai-build","commit_stats":null,"previous_names":["dimitarbez/ai-build"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/dimitarbez/ai-build","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimitarbez%2Fai-build","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimitarbez%2Fai-build/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimitarbez%2Fai-build/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimitarbez%2Fai-build/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dimitarbez","download_url":"https://codeload.github.com/dimitarbez/ai-build/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimitarbez%2Fai-build/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31405367,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["minecraft","minecraft-plugin","paper-mc"],"created_at":"2026-04-04T16:05:53.891Z","updated_at":"2026-04-04T16:05:54.650Z","avatar_url":"https://github.com/dimitarbez.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI Build - Minecraft Plugin\n\nA Minecraft Paper plugin that uses AI to help build structures in-game. Players can describe what they want to build, and the AI will generate the structure using Minecraft blocks.\n\n## Features\n\n- 🤖 AI-powered building using OpenAI\n- 🏗️ Natural language structure generation\n- 📝 Build history tracking\n- ✅ Build validation\n- 🔄 Support for block rotation\n\n## Requirements\n\n- Java 17 or higher\n- Paper MC 1.20.1 or compatible version\n- OpenAI API key\n\n## Building\n\nBuild the plugin using Gradle:\n\n```bash\n./gradlew build\n```\n\nOr using the Makefile:\n\n```bash\nmake build\n```\n\nThe compiled JAR will be in `build/libs/ai-build-0.1.0.jar`.\n\n## Installation\n\n1. Build the plugin (see above)\n2. Copy the JAR file to your Paper server's `plugins/` folder\n3. Configure your OpenAI API key (see below)\n4. Restart the server\n\n## Environment variables 🔒\n\nSet your OpenAI API key via environment variable:\n\n```bash\nexport OPENAI_API_KEY=\"sk-...\"\n```\n\nAlternatively, copy `.env.example` to `.env` in the project root and set the key there:\n\n```bash\ncp .env.example .env\n# then edit .env and set OPENAI_API_KEY\n```\n\n\u003e **Security:** Do **not** commit real API keys to source control. Add `.env` to `.gitignore`.\n\n### Using the included utility\n\nA small Java helper `EnvConfig.getOpenAiApiKey()` checks in this order:\n1. `System.getenv(\"OPENAI_API_KEY\")`\n2. `System.getProperty(\"OPENAI_API_KEY\")`\n3. A `.env` file in the project root\n\nThis lets you keep secrets in env vars or a local `.env` file for development.\n\n## Usage\n\nUse the `/aibuild` command in-game to create structures:\n\n```\n/aibuild \u003cdescription\u003e\n```\n\nExamples:\n- `/aibuild create a small wooden house`\n- `/aibuild build a stone tower 10 blocks tall`\n- `/aibuild make a bridge across this gap`\n\n### Undo Command\n\nUndo the last build:\n```\n/aibuild undo\n```\n\n## Configuration\n\nThe plugin creates `plugins/AIBuild/config.yml` with these options:\n\n```yaml\nopenai:\n  api_key: \"sk-proj-PUT_YOUR_ACTUAL_KEY_HERE\"\n  model: \"gpt-4o-mini\"\n  max_blocks: 500\n  timeout_ms: 60000\n\nbuild:\n  place_per_tick: 150           # Blocks placed per game tick\n  cooldown_seconds: 30          # Cooldown between builds\n  forward_offset_blocks: 3      # Distance in front of player\n  replace_only_air: true        # Only replace air blocks\n  allowed_materials:            # List of allowed materials\n    - OAK_PLANKS\n    - COBBLESTONE\n    # ... more materials\n\ndebug:\n  enabled: false                # Enable performance timing logs\n```\n\n## Project Structure\n\n```\nsrc/main/java/com/example/aibuild/\n├── AIBuildCommand.java       # Main command handler\n├── AIBuildPlugin.java        # Plugin entry point\n├── BlockPlacer.java          # Block placement logic\n├── BuildHistory.java         # Build tracking\n├── BuildValidator.java       # Build validation\n├── EnvConfig.java            # Environment configuration\n├── OpenAIClient.java         # OpenAI API integration\n├── Rotation.java             # Block rotation utilities\n├── exception/\n│   ├── BuildValidationException.java\n│   ├── OpenAIException.java\n│   └── PlanParseException.java\n├── model/\n│   ├── BlockSpec.java\n│   ├── BuildPlan.java\n│   └── Size.java\n├── service/\n│   ├── ConfigService.java\n│   └── PlanParser.java\n└── util/\n    └── DebugTimer.java\n```\n\n## Testing\n\nRun tests using Gradle:\n\n```bash\n./gradlew test\n```\n\nTest coverage includes:\n- **BuildValidator**: 18 unit tests for validation logic\n- **Rotation**: 17 unit tests for coordinate transformations\n- **PlanParser**: 6 unit tests for JSON parsing\n- **OpenAIException**: 7 unit tests for error handling\n\nSee [REFACTORING.md](REFACTORING.md) for details on the production-ready improvements.\n\n## Dependencies\n\n- Paper API 1.20.1\n- OkHttp 4.12.0 (HTTP client)\n- Gson 2.10.1 (JSON parsing)\n\n## License\n\nThis project is provided as-is for educational and personal use.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit issues or pull requests.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdimitarbez%2Fai-build","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdimitarbez%2Fai-build","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdimitarbez%2Fai-build/lists"}