GamesAI

Группа QQ по плагину/моду GamesAI: 849544707 — присоединяйтесь, чтобы обсуждать проблемы, делиться отзывами и обмениваться промптами, навыками и настройками инструментов!

Добро пожаловать в GamesAI for Fabric! Этот мод добавляет ИИ-ассистентов в Minecraft — задавайте вопросы, управляйте данными и настраивайте ИИ-бэкенды прямо из игры.

Из-за ограниченных сил автора мы не будем поддерживать версии ниже 1.21 и загрузчики, отличные от Fabric.

Установка

Требования

• Minecraft 1.21+ (или совместимая с Fabric версия — см. Совместимость версий)
• Fabric Loader ≥ 0.16.10
• Fabric API (последняя для вашей версии MC)
• Java 21 или новее

Установка

1. Скачай последний .jar с Modrinth
2. Положи его в папку .minecraft/mods/
3. Запусти игру с Fabric Loader
4. При первом запуске создаётся файл конфигурации по умолчанию: config/games_ai/config.json
5. Отредактируй конфиг, указав свои API-данные, затем перезагрузи командой /gamesai reload

Как вариант, скачай .jar со страницы GitHub Releases и положи его в папку .minecraft/mods/ тем же способом.

Использование

Команды ask

Поддерживаются только короткие флаги (-m, -n). Длинные формы (--model, --no-history) недоступны, чтобы не дублировать подсказки встроенных команд Minecraft.

Команды управления

Общие

История

Конфиг

Данные

Клиентские команды

Экран конфигурации в игре

Нажми F6 (по умолчанию), чтобы открыть визуальный экран настройки

• Общие настройки — редактируй prefix, max_history, lang, default_ai с помощью слайдеров, текстовых полей и кнопок переключения
• Профили ИИ — добавляй, редактируй или удаляй конфигурации бэкендов ИИ в визуальном редакторе
• Изменения сохраняются в config.json и применяются сразу

Чтобы переназначить клавишу экрана конфигурации: Настройки → Управление → Назначения клавиш → Разное → Open GamesAI Config

Конфигурация

При первом запуске создаётся конфиг по умолчанию:

.minecraft/config/games_ai/config.json

Структура по умолчанию

{
  "prefix": "[GamesAI]",
  "max_history": 10,
  "lang": "en_us",
  "all_ai": {
    "example_ai": {
      "prompt": "You are a helpful assistant in Minecraft.",
      "ai_name": "[GamesAI]",
      "base_url": "<Your Base URL>",
      "ai_model": "<Your AI Model>",
      "api_key": "<Your API Key>",
      "extra_body": {}
    }
  },
  "default_ai": "example_ai"
}

---

### 1. prefix

| Свойство | Значение |
|----------|-------|
| **Тип** | `String` |
| **По умолчанию** | `[GamesAI]` |

Имя плагина, используемое как префикс в ответах. Может содержать коды форматирования Minecraft.

---

### 2. max_history

| Свойство | Значение |
|----------|-------|
| **Тип** | `int` |
| **По умолчанию** | `10` |

Максимальное количество реплик диалога, сохраняемых для каждого игрока по каждой модели. Установите `0`, чтобы отключить историю. История хранится в памяти и очищается при перезапуске сервера.

---

### 3. lang

| Свойство | Значение |
|----------|-------|
| **Тип** | `String` |
| **По умолчанию** | `en_us` |
| **Варианты** | `en_us`, `zh_cn` |

Язык отображения для всего сервера. Изменения вступают в силу после `/gamesai reload`.

---

### 4. all_ai

| Свойство | Значение |
|----------|-------|
| **Тип** | `dict` |

Все записи конфигурации ИИ. Каждая запись — это словарь (ключ — внутренний AI_ID):

| Поле | Описание |
|-------|-------------|
| **prompt** | Системный промпт для этого ИИ. Используйте `> filename.md`, чтобы загрузить из `config/games_ai/prompt/`. |
| **ai_name** | Отображаемое имя в чате (может содержать коды форматирования Minecraft). |
| **base_url** | URL эндпоинта API (например, `https://api.openai.com/v1`). |
| **ai_model** | Название модели (например, `gpt-4o`, `deepseek-chat`). |
| **api_key** | Ключ аутентификации API. |
| **extra_body** | Дополнительные параметры, передаваемые в API (например, `{"thinking": {"type": "enabled"}}` для DeepSeek). По умолчанию: `{}`. |

#### Пример с несколькими профилями

```json
{
  "all_ai": {
    "gpt4o": {
      "prompt": "You are a Minecraft expert.",
      "ai_name": "[GPT-4o]",
      "base_url": "https://api.openai.com/v1",
      "ai_model": "gpt-4o",
      "api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "extra_body": {}
    },
    "deepseek": {
      "prompt": "You are a helpful Minecraft assistant.",
      "ai_name": "[DeepSeek]",
      "base_url": "https://api.deepseek.com",
      "ai_model": "deepseek-chat",
      "api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "extra_body": {}
    },
    "local_llama": {
      "prompt": "You are a friendly Minecraft assistant.",
      "ai_name": "[Llama3]",
      "base_url": "http://localhost:11434/v1",
      "ai_model": "llama3",
      "api_key": "ollama",
      "extra_body": {}
    }
  },
  "default_ai": "gpt4o"
}

Для Ollama / локальных моделей укажите api_key как "ollama" в качестве заглушки.

5. default_ai

Модель, используемая, когда игрок просто вводит /ask. Должна быть одним из ключей в all_ai.

Ссылка на файл промпта

Вместо того чтобы встраивать длинные промпты в config.json, можно ссылаться на внешние файлы:

1. Поместите файл промпта в config/games_ai/prompt/ (например, my_prompt.md)
2. Установите "prompt": "> my_prompt.md" в профиле ИИ

Мод автоматически читает содержимое файла во время запроса. Поддерживается любой текстовый формат (.md, .txt и т. д.).

Система базы данных

GamesAI включает публичную базу данных на основе SQLite по пути config/games_ai/database/database.db.

ИИ также может читать и записывать в базу данных через встроенные инструменты (ai_read_data, ai_write_data, ai_add_data, ai_del_data).

Инструменты ИИ

ИИ может вызывать функции для взаимодействия с Minecraft и базой данных.

Встроенные инструменты

Пользовательские инструменты через Groovy

Вы можете расширить возможности ИИ, написав скрипты на Groovy:

1. Поместите файлы .groovy в config/games_ai/tools/
2. Пометьте методы аннотацией @RegisterTool:

import java.util.function.Consumer;
import io.github.pengzixuan30.gamesai.tools.GamesAIToolsRegister;

@GamesAIToolsRegister.RegisterTool(
    name = "my_custom_tool",
    description = "Does something useful",
    parameters = """
        {
          "type": "object",
          "properties": {
            "param": {
              "type": "string",
              "description": "The value to process"
            }
          },
          "required": ["param"]
        }
        """
)
String myCustomTool(Consumer<String> feedback, String aiName, String param) {
    feedback.accept("Executing custom tool...")
    return "Result: ${param} processed"
}

В сигнатуре метода инструмента обязательно должны идти `Consumer feedbackпервым параметром иString aiNameвторым, а после них — любые пользовательские параметры, объявленные в JSON-схемеparameters`.

3. Перезагрузите командой /gamesai reload — инструменты обнаруживаются и регистрируются автоматически.

Навыки

Навыки — это Markdown-файлы, которые дают ИИ знания и инструкции по конкретной области. ИИ может читать их через инструмент read_skills.

Добавление навыков

1. Поместите файлы .md в config/games_ai/skills/
2. Зарегистрируйте их в config/games_ai/skills/skills.json:

[
  {
    "skills": "my_guide.md",
    "summary": "A guide for building redstone machines"
  }
]

3. Перезагрузите командой /gamesai reload

Зарегистрированные навыки появляются в системном промпте ИИ, чтобы он знал, какие знания доступны.

Горячая перезагрузка

GamesAI предоставляет механизм горячей перезагрузки, который позволяет применять изменения конфигурации, инструментов, навыков и переводов без перезапуска сервера.

Запуск горячей перезагрузки

Горячую перезагрузку можно запустить следующими способами:

Что происходит при горячей перезагрузке

При выполнении горячей перезагрузки мод последовательно выполняет следующие шаги:

1. Повторное чтение файла конфигурации (config/games_ai/config.json) — применяются все изменения prefix, max_history, lang, all_ai, default_ai и т. д.
2. Перезагрузка переводов — применяется выбранный lang (en_us / zh_cn) без перезапуска.
3. Перезагрузка Skills (config/games_ai/skills/skills.json) — обновляется индекс навыков; список доступных навыков в системном промпте AI обновляется синхронно.
4. Перезагрузка пользовательских инструментов (config/games_ai/tools/*.groovy) — горячая загрузка кода пользовательских инструментов Groovy без перезапуска сервера.

Горячая перезагрузка не очищает историю чата игроков. История хранится в памяти и очищается только при перезапуске сервера.

Структура проекта

src/
├── main/java/io/github/pengzixuan30/gamesai/
│   ├── GamesAI.java                  # Точка входа мода — инициализация и загрузка конфигурации
│   ├── command/
│   │   └── GamesAICommands.java      # Регистрация и выполнение команд
│   ├── config/
│   │   ├── GamesAIConfig.java        # Модель данных конфигурации (профили AI, extra_body)
│   │   └── GamesAIConfigManager.java # Чтение/запись файла конфигурации (JSON, UTF-8)
│   ├── database/
│   │   └── GamesAIDatabase.java      # Публичная база данных SQLite
│   ├── help/
│   │   └── GamesAIHelp.java          # Контекстно-зависимая система справки
│   ├── openai/
│   │   └── GamesAIRequestAI.java     # Клиент OpenAI API и обработка ответов
│   ├── tools/
│   │   ├── GamesAIToolsRegister.java # Сканер аннотаций инструментов
│   │   ├── GamesAIBuiltinTools.java  # Реализации встроенных инструментов
│   │   └── GamesAIExternalToolsLoader.java # Загрузчик инструментов Groovy
│   └── translations/
│       └── GamesAITranslations.java  # Движок переводов I18n
├── main/resources/
│   ├── fabric.mod.json               # Метаданные мода Fabric
│   └── assets/games_ai/lang/         # Файлы переводов (en_us, zh_cn)
├── client/java/io/github/pengzixuan30/gamesai/client/
│   ├── GamesAIClient.java            # Клиентская точка входа — привязка клавиш, /c-ask
│   └── screen/
│       ├── GamesAIConfigScreen.java           # Главный экран конфигурации
│       ├── GeneralConfigEditScreen.java       # Редактор общих настроек
│       ├── AiProfileConfigEditScreen.java     # Редактор списка профилей AI
│       └── AiProfileDetailConfigEditScreen.java # Редактор деталей профиля AI
├── build.gradle
├── gradle.properties
└── settings.gradle

Архитектура

flowchart LR
    Config[json] -->|load| Manager[GamesAIConfigManager]
    Manager --> Model[GamesAIConfig]
    Model --> Main[GamesAI]
    Main --> Cmd[GamesAICommands]
    Cmd -->|/ask| API[GamesAIRequestAI]
    API -->|HTTP| OpenAI[OpenAI API]
    Main --> History[(allHistory)]
    History --> API
    API --> History
    API -->|response| Cmd
    Cmd -->|sendMessage| Player[Minecraft Player]
    Main --> DB[(GamesAIDatabase)]
    DB --> API
    Main --> Tools[GamesAIToolsRegister]
    Tools --> API
    GUI[Config Screen] --> Manager

Сборка

Требования

• JDK 21 (или новее)
• Gradle Wrapper (входит в комплект — используйте gradlew / gradlew.bat)

Сборка

git clone https://github.com/PengZixuan30/GamesAI.git
cd GamesAI
./gradlew build

Скомпилированный .jar будет здесь: build/libs/games_ai-*.jar

Среда разработки

./gradlew runClient    # Запустить клиент Minecraft с модом
./gradlew runServer    # Запустить локальный тестовый сервер

Решение проблем

/ask возвращает ошибки

Инструменты AI не работают

• Убедитесь, что инструменты зарегистрированы: проверьте лог сервера на [GamesAIToolsRegister] Registered tool: ...
• Для кастомных Groovy-инструментов проверьте config/games_ai/tools/ на синтаксические ошибки
• Включите режим отладки: /gamesai debug, чтобы увидеть полные промпты и результаты вызовов инструментов

Проблемы с экраном конфигурации

• Нажмите F6, чтобы открыть (проверьте привязку клавиш в Управление → Разное)
• Изменения конфигурации в GUI сохраняются только при нажатии "Save"
• Используйте "Undo", чтобы вернуться к последнему сохранённому состоянию

Что нового

Версия 0.2.0

🎯 Главное

• 🖥️ Экран конфигурации на стороне клиента — Визуальный GUI настройки прямо в игре (нажмите F6).
• 💬 Клиентская команда /c-ask — Спросите AI с клиента без прав на серверные команды.
• 🗄️ База данных, внешние промпты, навыки и кастомные инструменты — Публичная база данных SQLite, ссылки на промпты через > file.md, система навыков и кастомные инструменты на Groovy.
• 🧹 Режим без истории — /ask -n спрашивает AI без истории диалога (в соответствии с версией для MCDReforged).
• 🛠️ Вызов инструментов AI — AI теперь может вызывать встроенные и кастомные инструменты для взаимодействия с Minecraft и базой данных.
• ⚙️ Конфиг extra_body — Передавайте дополнительные параметры, специфичные для провайдера, в API для большей гибкости.

1. Экран конфигурации на стороне клиента

Нажмите F6 (по умолчанию), чтобы открыть визуальный экран конфигурации. Редактируйте общие настройки и профили AI с помощью слайдеров, текстовых полей и кнопок переключения — изменения сохраняются в config.json и применяются сразу. См. Экран конфигурации в игре.

2. Клиентская команда /c-ask

Новая клиентская команда /c-ask позволяет игрокам спрашивать AI с клиента без необходимости в правах на серверные команды. Поддерживает флаги -m (модель) и -n (без истории), как и /ask. См. Клиентские команды.

3. База данных, внешние промпты, навыки и кастомные инструменты

• Публичная база данных — Хранилище ключ-значение на SQLite, доступное для инструментов AI и команд. См. Система базы данных.
• Файлы внешних промптов — Ссылайтесь на внешние .md-файлы как на системные промпты через > filename. См. Ссылка на файл промпта.
• Навыки — Markdown-файлы, дающие AI знания в конкретной области. См. Навыки.
• Кастомные инструменты — Расширяйте возможности AI с помощью Groovy-скриптов. См. Кастомные инструменты на Groovy.

4. Режим /ask без истории

Используйте `/ask -n , чтобы спросить AI без использования истории диалога (в соответствии с !!ask -n` в версии для MCDReforged). См. Команды Ask.

5. Вызов инструментов AI

AI теперь может вызывать встроенные инструменты (поиск по Minecraft Wiki, калькулятор, вайтлист, база данных, навыки и т.д.) и кастомные Groovy-инструменты для выполнения действий в Minecraft. См. Инструменты AI.

6. Конфиг extra_body

Теперь каждый профиль ИИ поддерживает поле extra_body для передачи дополнительных параметров, специфичных для провайдера (например, {"thinking": {"type": "enabled"}} у DeepSeek). См. 4. all_ai.

Совместимость версий

Из-за ограниченных сил автора мы не будем поддерживать версии ниже 1.21 и загрузчики, отличные от Fabric.

Благодарности и отказ от ответственности

• DA100 — дизайн логотипа для этого мода
• FabricMC — фреймворк для моддинга
• openai/openai-java — официальная Java-библиотека OpenAI
• Minecraft — торговая марка Mojang / Microsoft. Этот мод не связан с Mojang.

Весь контент, сгенерированный моделями ИИ (LLM), не имеет отношения к этому моду.

Все последствия, возникающие из-за пользовательских инструментов, не имеют отношения к этому моду.

Спонсорство и участники

Адрес для спонсорства: Afdian

Те, кто спонсирует GamesAI, появятся в следующем списке спонсоров (на данный момент спонсоров нет):

Лицензия

• Исходный код распространяется под лицензией MIT — подробности см. в файле LICENSE.
• Логотип и визуальные материалы являются собственностью 冬天衣服不错, все права защищены. Вы можете просматривать и делиться ими для личного, некоммерческого использования, но любая модификация или коммерческое использование требует предварительного письменного разрешения.