search

tomekbielaszewski / MUD-Engine

GNU General Public License v3.0
2 stars 0 forks source link

readme

MUD-Engine Build Status

Dokumentacja

Spis treści

  1. Wstęp
  2. Instalacja, konfiguracja i pierwsze uruchomienie
  3. Lokalizacje plikow gry
  4. Komendy
  5. Gracz
  6. Skrypty
  7. Przedmioty
  8. Lokacje
  9. Teksty powiadomień
  10. Administrator

Wstęp

MUD-Engine jak sama nazwa wskazuje jest silnikiem do tworzenia gier typu MUD, czyli Multi User Dungeon. Interakcja z grami tego typu odbywa się wyłącznie za pomocą komend i czytania opisów. Silnik w całości napisany jest w Javie, natomiast skryptowany jest w JavaScripcie, a definicje przedmiotów, lokacji itp sa zapisane jako JSON. Zmienne elementy gry, takie jak model gracza czy przedmioty na lokacjach, zapisywane są w bazie Postgres.

Instalacja, konfiguracja i pierwsze uruchomienie

Silnik budowany jest z myślą o zachowaniu minimalnych zależności i minimalnej konfiguracji, więc do działania wymaga jedynie Javy 8 i Postgres 10.

Wymagana/zalecana konfiguracja to

Plik application.properties (opcjonalne)

Jest to plik szeroko opisany w dokumentacji Spring Boot. Zalecana konfiguracja to:

Plik assets.properties (wymagane)

W tym pliku definiujemy lokalizacje główne dla wszystkich assetów (lokacje, itemy, skrypty) Więcej info patrz -> Lokalizacje plikow gry

Plik command-mapping.properties (wymagane)

W pliku znajduje się mapowanie komend do klas implementujących ich działanie. Tzw komendy systemowe. Więcej info patrz -> Komendy

Plik strings.properties (wymagane)

W pliku znajdują się wszystkie komunikaty występujące w silniku Więcej info patrz -> Teksty powiadomień

Lokalizacje plikow gry

Lokalizacje plikow gry domyslnie znajdują się pod:

Przy czym sciezki do folderów można modyfikować przez zmianę ścieżek do nich w pliku assets.properties, gdzie:

Komendy

Jedyny sposób interakcji ze światem odbywa się przez komendy wywoływane przez gracza. Silnik posiada zaimplementowane podstawowe komendy jak i pozwala na implementację własnych - powiązanych z przedmiotami.

Wbudowane komendy

Komendy wbudowane dostępne dla wszystkich graczy:

Komendy wbudowane dostępne dla administratorów:

Mapowanie komend

Wbudowane komendy są zmapowane do słów pozwalających na wywołanie ich. Takie mapowanie znajduje się w pliku command-mapping.properties. W pliku tym znajdziemy pary klucz wartośc gdzie:

Parametry komend

Komendy wymagające podania parametrów wejściowych:

Gracz

Statystyki/karta gracza

Parametry

Ekwipunek

Walka

Skrypty

pliki konfiguracyjne skryptów i mapowanie skryptów

Plikiem konfiguracyjnym skryptów jest plik JSON znajdujący się w folderze domyślnym scripts [*]:

[
  {
    "id": "100",
    "name": "Always true script",
    "path": "scripts/js/alwaysTrue.js"
  }
]

Gdzie:

W pliku pod ścieżką podaną w zmiennej path znajduje się właściwy kod skryptu.

Silnik JavaScript - Nashorn

Skrypty odpalane są za pomocą silnika JavaScript Nashorn. Znaczy to, że można w skryptach używać wszystkiego na co silnik ten pozwala włącznie z obiektami Java. Przystepne materiały można znaleźć tutaj i tutaj

Podstawowe zmienne

W każdym odpalonym skrypcie jest dostęp do następujących zmiennych podstawowych:

W przypadku skryptów odpalanych przez gracza za pomocą komendy z parametrami, parametry te są zmapowane do zmiennych w skrypcie. Przykładowo komenda uruchamiająca skrypt craftingu w kowadle zdefiniowana jako:

{
    "command": "wykuj (?<itemName>[\\D]+) (?<amount>[\\d]+)",
    "scriptId": "bs-anvil-crafting"
}

ma zadeklarowane 2 parametry wejściowe "itemName" i "amount", które zostaną zmapowane do zmiennych w kodzie JS. Przy czym każda zmienna będzie miała typ String, a w przypadku zmiennej "amount" należy sprawdzić jej istnienie i ewentualnie zainicjalizować ją wartością domyślną (patrz linijka 17 w anvil/crafting.js)

Dostęp do serwisów i klas pomocniczych silnika

Zmienne pod którymi dostępne są serwisy ułatwiające interakcję ze światem gry: Repozytoria: //TODO skonczylem tutaj

Serwisy

Konwertery

Zwracanie wartości

Wartość jaką zwróci skrypt jest wartością zwróconą przez ostatnią funkcję w skrypcie. Przykładową konstrukcją zwracającą zawsze wartość true jest:

function alwaysTrue() {
    // here goes all the script instructions
    return true;
}
alwaysTrue();

Obecnie zwracana wartość jest brana pod uwagę jedynie w przypadku skryptów beforeX na lokacjach. Skrypty są predykatami do wykonywanej lokacji i muszą zwracać wartość typu Boolean.

Skrypty specjalne

Master script

Skrypty pomocnicze

Skrypt administratorski

Przedmioty

Model przedmiotów

Pliki JSON opisujące właściwości przedmiotów znajdują się w folderze domyślnym items [*]. Przykładowy wpis w pliku:

[
  {
    "id": "1",
    "name": "Złota moneta",
    "description": "Sporawy, złoty krążek z wizerunkiem jednego z dawno juz nie żyjących władców.",
    "itemType": "MISC",
    "commands": [
      {
        "command": "dzyn-dzyn",
        "scriptId": "101"
      }
    ]
  }
]

Gdzie:

W przypadku przedmiotów innych typów niż MISC dostępne są także dodatkowe zmienne. O tym poniżej

Komendy, mapowanie i skryptowanie komend

Jak opisano wyżej - przedmioty można oskryptować, za pomocą zmapowania skryptu w pliku konfiguracyjnym JSON. W przypadku zmapowania komendy przedmiotu do nieistniejącego skryptu - zostanie wyrzucony wyjątek podczas uruchamiania gry. Jednak jeśli zostanie zmapowanych kilka identycznych komend do różnych skryptów - nie jest gwarantowane który skrypt zostanie uruchomiony. Skrypty uruchamiane na przedmiotach nie oczekują zwrócenia żadnej wartości, także taka konstrukcja nie ma w tym przypadku zastosowania.

Rodzaje przedmiotów

Istnieją obecnie 4 typy przedmiotów - [WEAPON,ARMOR,MISC,STATIC]. Niektóre typy, oprócz zmiennych podstawowych [id,name,description,itemType,commands], posiadają także dodatkowe zmienne:

Lokacje

Model lokacji

Skryptowanie lokacji

Przedmioty statyczne

Teksty powiadomień

Klucze wiadomości

Administrator

Nadawanie praw administratora

Komendy administratora