# Nidarel Adventurer — towarzysz AI (mod ai_companion)

> Źródło: repo ai-companion/docs/wiki/towarzysz-ai.md. Edytuj w repo, nie tutaj.

> **Stan: działa na Nidarelu od 25.10.2026.** Mod pobierzesz z [ariku.pl/download](https://ariku.pl/download) (sekcja mody, obok authlogic). Bez niego w paczce serwer cię nie wpuści.

**Nidarel Adventurer** to towarzysz AI: postać w świecie Minecrafta, która chodzi za tobą, rozmawia na czacie i wykonuje polecenia. Kopie rudy, walczy z potworami, rzuca zaklęcia i pamięta, co ustaliliście.

Za myślenie odpowiada model językowy, Gemini 3.8 Flash. Za działanie odpowiada kod serwera. Model wybiera, co zrobić i jak to powiedzieć. Serwer sprawdza każdą akcję i dopiero wtedy ją wykonuje. Towarzysz nie wpisuje komend i nie dostaje uprawnień gracza.

## Co trzeba mieć

- Plik `ai_companion-0.1.0.jar` z [ariku.pl/download](https://ariku.pl/download) w folderze `mods` **na swoim kliencie**, czyli w tej samej paczce ATM10 co serwer. Bez niego serwer z modem cię nie wpuści, bo towarzysz to nowy rodzaj stworzenia, który musi znać też klient.
- Nic więcej. Model działa po stronie serwera, a ty nie potrzebujesz żadnego klucza.

## Pierwsze kroki

1. Wpisz `/companion summon`. Obok ciebie pojawi się twój towarzysz, domyślnie **Mędrzec**.
2. Daj mu kilof albo miecz. Kliknij go prawym przyciskiem z przedmiotem w ręce. Zbroję założy sam.
3. Napisz do niego na czacie:
   - `@Mędrzec znajdź diamenty, wykop 8 i wróć do mnie`
   - `Mędrzec, zostań tutaj`
   - `@ai co widzisz w okolicy?`

Towarzysz odpowie na czacie, powie, co zamierza zrobić, i zda raport, kiedy skończy. Jeśli nie wie, o co ci chodzi, dopyta, zamiast zgadywać.

Każdy gracz ma jednego towarzysza. Inni gracze nie mogą mu wydawać poleceń, chyba że im na to pozwolisz: `/companion share <nick>`.

## Najważniejsze komendy

| Komenda | Co robi |
|---|---|
| `/companion summon` / `dismiss` | przywołuje albo odsyła; pamięć i przedmioty zostają |
| `/companion follow` / `stay` / `defend` / `stop` | idź za mną / zostań / broń mnie / przerwij |
| `/companion status` | zdrowie, mana, zadanie, ekwipunek |
| `/companion mine <ruda> [ile]` | kopanie bez modelu, np. `/companion mine iron 16` |
| `/companion give` | oddaje ci wszystko, co uzbierał (albo kucnij i kliknij go pustą ręką) |
| `/companion skill <umiejętność>` | `lightning_strike`, `arcane_bolt`, `shield`, `healing`, `emergency_escape`, `summon_creature` |
| `/companion personality list` / `set <id>` | zmiana charakteru, tylko twojego towarzysza |
| `/companion skin <wygląd>` | `default`, `wise_one`, `orin`, `steve`, `alex` |
| `/companion memory mark <nazwa>` | zapamiętuje to miejsce, np. `baza`; potem „idź do bazy” |
| `/companion memory clear` | czyści jego pamięć |

## Kopanie

- Kopie tylko rudy z listy serwera: węgiel, żelazo, miedź, złoto, redstone, lapis, diamenty, szmaragdy, kwarc oraz rudy z modów (cyna, osm, ołów, uran, cynk, srebro, nikiel). Drewno też.
- Szuka w promieniu do 48 bloków i tylko w załadowanych chunkach. Nie generuje nowego świata.
- Gdy do rudy nie ma przejścia, przekopuje się tunelem przez kamień, ziemię i żwir. Nigdy nie kopie prosto w dół.
- **Nie kopie obok lawy.** Przy ostrożnym trybie omija też wodę i luźny żwir nad głową.
- Szanuje claimy (FTB Chunks). Sprawdza każdy blok tak, jakbyś to ty go kopał, więc musisz być wtedy w grze.
- Odkłada narzędzie, zanim się zepsuje. Nie zniszczy ci kilofa.

## Walka i umiejętności

- Broni się, broni ciebie, a w trybie `defend` sam atakuje potwory w pobliżu.
- **Nigdy nie atakuje graczy**, oswojonych zwierząt, osadników ani golemów.
- Przy niskim zdrowiu się wycofuje.
- Ma własną manę i własne umiejętności. Błyskawica domyślnie nie wywołuje pożaru i rani tylko cel.
- Gdy na serwerze jest Iron's Spells 'n Spellbooks, magiczny pocisk rzuca jako prawdziwe zaklęcie z tego moda. Nie strzela, kiedy stoisz na linii ognia.

## Osobowości

| id | Kto to |
|---|---|
| `sage` | Mędrzec: spokojny, rozważny, czasem zagadkowy |
| `guardian` | Strażnik: krótkie ostrzeżenia, najpierw twoje bezpieczeństwo |
| `trickster` | Figlarz: żarty i nietypowe pomysły, ale w granicach zasad |
| `scholar` | Badacz: komentuje odkrycia, oddziela fakty od przypuszczeń |
| `silent` | Milczek: odzywa się tylko w ważnych sprawach |
| `chaotic` | Szaleniec: głośny, odważny, dramatyczny |

Osobowość zmienia sposób mówienia, gadatliwość i taktykę. Nie zmienia tego, co towarzyszowi wolno. Administrator może dodać własne osobowości jako pliki JSON.

## Gdy model nie działa

Towarzysz działa dalej. Rozumie wtedy proste polecenia, na przykład „chodź”, „zostań”, „stop”, „wykop 10 żelaza” czy „pilnuj”, i odpowiada krótkimi gotowymi zdaniami. Serwer się nie zacina, bo rozmowa z modelem odbywa się w tle.

## Dla administratora

- Konfiguracja jest w `config/ai_companion-common.toml`: backend modelu, limity, listy dozwolonych bloków, walka i umiejętności. Klucz API nigdy nie jest zapisywany w pliku, tylko w zmiennej środowiskowej.
- Dokumentacja techniczna leży w repo `ai-companion`: README, `docs/ARCHITECTURE.md`, `docs/SECURITY.md`, `docs/COMPATIBILITY.md`, `docs/TESTING.md`.
- Testy z 24.10.2026:
  - 83 testy jednostkowe;
  - 10 testów w świecie na czystym NeoForge;
  - 9/9 scenariuszy na pełnej paczce ATM10 8.3, w tym prawdziwe polecenie przez Gemini i zaklęcie Iron's.
- Panel konfiguracji: ariku.pl → GAMING → **Nidarel Adventurer**. Zmiany (osobowość, wygląd, tryb, charakter, pamięć) serwer stosuje przy najbliższej synchronizacji, gdy twój towarzysz jest w świecie.