Embed Size (px)
Citation preview
Alcarin DocumentationRelease 0.2.6
psychowico
December 28, 2013
Contents
1 Alcarin - Opowiesc (pl) 31.1 Swiat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Zycie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2 Mechanika gry 52.1 Czas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2 Zwykli gracze . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.3 Substancje . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.4 System metryczny . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3 Installation instructions 93.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4 Dev: How to? 114.1 How to define access permissions for page? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.2 How to add coffee/less files to project? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
5 Programming 135.1 Preparing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135.2 Architecture design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145.3 Guard configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
6 AJAX programming 176.1 Urls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176.2 RESTful requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
7 Zend Framework 2 extensions 197.1 Controller Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197.2 View Helpers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
8 Plugable game services 218.1 GameServiceContainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218.2 Custom GameObjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
i
8.3 Common services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
9 Logging 25
10 Forms 2710.1 Default form fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2710.2 Registration custom validators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2710.3 Registration custom filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
11 Indices and tables 29
ii
Alcarin Documentation, Release 0.2.6
Alcarin will be a fantasy, persistent browser-based role-playing game. This documentation is divided into few parts.I would eventually translate all docs to english, but for my convenience most parts will be only in polish until Ideveloping this project myself - sorry!
Contents:
Contents 1
Alcarin Documentation, Release 0.2.6
2 Contents
CHAPTER 1
Alcarin - Opowiesc (pl)
Narazie wrzuce tutaj troche opisu swiata gry i luzno powiazanych mysli, ta czesc bedzie wazniejsza w przyszłosci.
1.1 Swiat
Swiat w Alcarin nie przypomina naszej planety. Jest mieszanka mitologii indyjskiej, ksiazek Tolkiena, Pratchett’ai innych. Planeta ma kształt dysku, opiera sie o plecy czterech słonii, które stoja na wielkich zółwiu pływajacymw przestrzeniach wszechswiata. Swiatło i ciepło planecie daje olbrzymia latarnia znajdujaca sie na szczycie wielkiejkolumny postawionej przez bogów w centrum swiata. Latarnia ta pulsuje, tak ze mamy atmosfere podobna do naszegodnia i nocy. Jednak dzien trwa dwie nasze doby (48h), tak samo jak i noc. Z tego wynika, ze pełny obrót latarnii zaj-muje jej 4 doby czasu naszego swiata. Na planecie nie ma wyraznych pór roku, za to sa obszary znacznie rózniace sieklimatem - na obrzezach planety panuje wieczne zlodowacenie (dzieki temu oceny nie “spływaja”), za to w okolicachcentrum mamy cos w rodzaju tropikalnej dzungli.
1.2 Zycie
1.2.1 Rosliny
W swiecie magii i pradawnych mocy czasem trudno okreslic, co jest roslina a co zwierzeciem. Nie zdziw sie jeslibedzie zmuszony uciekac gdy w trakcie polowania spotkasz gigantyczne drzewo, któremu nie spodoba sie twojetowarzystwo.
1.2.2 Zwierzeta
Niektóre zwierzeta na tej planecie sa odpowiednikiem zyjacych na ziemi, jednak spotkac mozna tam tez wiele niez-nanych nam istot. Zwierzeta potrafia sie rozmnazac i czasem podrózowac, ich aktywnosc (i co za tym idzie przykład-owo szansa upolowania, albo niesione zagrozenie) moze róznic sie zaleznie od tego, czy trwa noc, czy tez dzien.
1.2.3 Humanoidy
Na Alcarin mozna spotkac wiecej niz jeden typ intelegintnych istot. Na pewno beda to elfy, krasnolodu i ludzie, jednakbyc moze potem znajdzie sie tego wiecej.
3
Alcarin Documentation, Release 0.2.6
1.2.4 Nadprzyrodzone
Alcarin to swiat magii i bogów. Chodz nie zdarza sie to czesto, czasem mozna spotkac istoty wszechpotezne, którychmoc wydaje sie pochodzic od bóstw. Czasem niosace groze, innym zas razem ukojenie.
4 Chapter 1. Alcarin - Opowiesc (pl)
CHAPTER 2
Mechanika gry
2.1 Czas
Pełen cykl dobowy bedzie trwał 24 * 4 = 96 godzin. Czyli dzien bedzie trwał dwie nasze doby, po którym nastapi noc,trwajaca podobnie. Wszelkie wystapiania słowa “dzien” ponizej odnosza sie do dnia swiata gry.
W grze istnieje absolutny czas, zgodny w kazdym fragmencie swiata (z dokładnoscia do sekundy). Mozemy takzeokreslic czas lokalny - to jest zalezny od pozycji w przestrzeni. Jest przydatny przykładowo przy obliczaniu oswietle-nia. Godziny liczymy od 0 do 96, ale w swiecie uzywamy okreslen od 0 do 24 dniowa i od 0 do 24 nocna.
2.1.1 Współrzedne
Swiat uzywa kartezjanskiego systemu współrzednych o odbitej osi Y, z punktem (0, 0) w centrum swiata. Czyli Yrosnie w dół mapy, X rosnie w jej prawa strone.
2.1.2 Oswietlenie
Swiat Alcarin jest oswietlany przez Wielka Latarnie (Great Lighthouse) postawiona w jego centrum poprzez bogów.Latarnia jest umiejscowiona na olbrzymim tworze skalnym o prawie płaskich scianach, o wysokosci około 5 kilo-metrów i szerokosci przy podstawie około jednego kilometra. Jest takze zródłem ciepła - tereny połozone najblizej jejprzypominaja okolice równikowe na Ziemi - zas ziemie połozone najdalej - Antarktyde.
Wielka Latarnia cyklicznie pulsuje, swiecac przez 48h i gasnac na kolejne 48h - tworzac w ten sposób system dobowy.
Pory Dnia
Godzine 0 uznajemy za poczatek dnia. Latarnia wtedy sie rozgrzewa, zaczyna robic sie jasno. Pory prezentuja sienastepujaco:
• od 44N.(nocnej) do 4D.(dziennej) mamy poranek
• od 4D. do 44D. mamy pełnie dnia (pełne oswietlenie)
• od 44D. do 4N. mamy wieczór
• od 4N. do 44N. mamy noc (praktyczny brak oswietlenia)
5
Alcarin Documentation, Release 0.2.6
2.2 Zwykli gracze
Zwykły gracz moze stworzyc do 3 postaci. Sa dwie mozliwosci powstania postaci:
• zamieszkanie w ciele 5-letniego dziecka (wymaga istnienia takie dziecka w swiecie, prawdopodbnie bedziesie wiazała z długim oczekiwaniem)
• przebudzenie sie postaci w wieku 20 lat, w jakis fabularny sposób, zaleznie od rasy
Postacie zyja normalnie około 90 dni, po czym zaczynaja sie starzec. W wieku 140 dni sa juz zupełnie słabi i podatnina wszelkie słabosci, moga zginac od zadrapan etc. Gdyby jakas postac dozyła 200 dni, od tej granicy codziennie ma5% szans na naturalna smierc. Konsekwencja starzenia jest osłabienie wszelkich zdolnosci(szczególnie siły fizycznej)jednak z pamietanym “najwyzszym” poziomem i mozliwoscia uczenia innych według niego.
2.3 Substancje
Na poczatek mały słowniczek:
• substancja - dowolny typ obiektu, tak surowiec, jak przedmiot
• obiekt - instancja substancji
• cechy - zbiór własciwosci okreslajacy mozliwosc interakcji obiektu ze swiatem, jak jego palnosc, wytrzymałosc,czy twardosc. Od tego zalezy, jak dobrze bedzie sie palił dany obiekt etc.
• zródło - abstrakcyjne pojecie okreslajace zbiór substancji jakie moga byc pozyskiwane. zródła przypisuje sie dookreslonych obszarów
Stwierdzilismy, ze wszelkie uzywalne surowce jak i szeroko rozumiane narzedzia beda nalezec do tej samej grupy -substancji. Mozna je uzyskac na jeden z dwóch sposobów: pozyskac ze zródła, lub wyprodukowac (prawdopodobnieprzy uzyciu innych substancji i narzedzi). Substancje charakteryzuja sie nastepujacymi własciwosciami:
• nazwa (name) - unikalna nazwa bazowa substancji (np. hammer)
• etykieta(label) - tłumaczalny ciag uzywany do wygenerowania nazwy substancji w grze, z uzyciem jej głównegoskładnika (np. “{{material}} młotek”)
• opis(description) - słowny opis wygladu i podstawowych własciwosci substancji
• stan skupienia(state of matter) - stan skupienia materii, jeden z czterech:
– gazowy(gas) - przenoszony jedynie w dedykowanych pojemnikach, samoczynnie po prostu rozpływasie w powietrzu
– ciekły(liquid) - przenoszony w wiekszosci pojemników, samoczynnie rozlewa sie i zatraca
– sypki(powder) - moze lezec na ziemi w dowolnej ilosci, zmienny kształt
– sztuki(units) - jako jedyny liczony w sztukach, a nie w pojemnikach (czyli niedoszacowanej objetosci,sprawdz dokument “System metryczny”); moze lezec na ziemi i byc noszony w pojemnikach, czestoduza objetosc wzgledem masy
• cechy(properties) - zbiór własciwosci okreslajacy mozliwosc interakcji obiektu ze swiatem, jak jego palnosc,wytrzymałosc, czy twardosc. Od tego zalezy, jak dobrze bedzie sie palił dany obiekt etc. Obiekty pozyskiwaneze zródeł przyjmuja wartosc tych własciwosc zaleznie od ustawien zródła. Obiekty tworzone przez postaciezyskuja je domyslnie przy pomocy obliczania sredniej wazonej substancji uzytych przy wytwarzaniu danegoobiektu. Jednak kazda z wartosci cech konkretnej substancji mozna nadpisac własnym wzorem, uzywajacymwszelkich innych cech tej substancji.
6 Chapter 2. Mechanika gry
Alcarin Documentation, Release 0.2.6
• jakosc(quality)- jakosc jest specjalnym typem cechy. Charakteryzuje sie tym, ze domyslnie nie jest obliczanajedynie przy uzyciu sredniej wazonej jakosci uzytych substancji, ale takze przy uwzglednieniu starannosci pracy,umiejetnosci rzemieslnika, jakosci uzytych narzedzi.
Jako zródło substancji rozumiemy abstrakcyjny zestaw informacji który moze byc wykorzystany do wygenerowaniaokreslonych substancji z okreslonymi cechami(jak jakosc, palnosc), o okreslonymi bogactwie etc.
Zródła składaja sie z listy generowanych substacji (czesto jednej). Samo zródła posiada jedynie podstawowe własci-wosci:
• etykieta(label) - domyslny tłumaczalny ciag uzywany do wygenerowania nazwy zródła substancji w grze (np.“Las”, “Kopalnie”). Postacie powinny miec mozliwosc zapamietywania własnej nazwy dla kazdej instancjizródła
• opis(description) - krótki opis fabularny zródła
Kazdy z wpisów na liscie substancji charakteryzuje sie nastepujacymi własciwosciami:
• substancja (resource) - po prostu wczesniej przygotowany typ substancji
• bogactwo(richness) - podana jako sumaryczna dostepna masa tuz po stworzeniu zasobu
• odnawialnosc(recovery) - z jaka szybkoscia zródło bedzie sie odnawiac przy pozostawieniu odłogiem - mozebyc to wzór wykorzystujacy inny współczynnik (tak, by po zupełnym wykarczowaniu lasów na danym obszarzepraktycznie przestały odrastac, etc. )
• cechy(properties) - zakresy cech substancji (takze jako wzory) jakie moga zostac otrzymane z tego zródła
Instancja zródła(source instance) wyróznia sie od typu zródła posiadaniem informacji o stopniu zuzycia kazdej zgenerowanych substancji.
2.4 System metryczny
Mierzenie wszystkich wag w dokładnych wartosciach masy - np. w gramach, jak w Cantrze, jest nienaturalne ipowoduje rózne głupie sytuacje w grze. Ogranicza ludziom wyobraznie dokładnoscia, uniemozliwia oszukiwanie itp.Postanowilismy, ze nasz system powinien charakteryzowac sie nastepujacymi cechami:
• brak koniecznosci uzywania dokładnej ilosci zasobów
• brak stałej, dokładnej jednostki metrycznej (ze strony graczy) - zamiast tego uzywanie rozmaitych miarek -bazowo “szczypty” i “garsci” (potem innych pojemników)
• niedokładnosc miarek - zaleznie od dokładnosci wykonania ten sam typ kubka moze róznic sie objetoscia
• po stronie serwera wszelkie instancje pojemników maja tak okreslona pojemnosc (objetosc), jak i okreslonailosc masy jaka moga pomiescic. w wielu przypadkach bedzie to bardzo duza masa i faktyczne znaczeniebedzie miała objetosc
Szczegóły:
• istnieja dwie typy naturalnych miarek: szczypta i garsc
• kazda postac ma troche inna garsc/szczypte
• szczypta to ( 4ml +/- 25%, czyli 3ml-5ml ) stała dla postaci
• garsc to ( 100ml +/- 15%, czyli 85ml-115ml ) stała dla postaci
Osoba bedzie widziała zasoby w swoim inwentarzu, czy w otoczeniu poprzez najlepiej dopasowany pojemnik jakima w plecaku (niech to bedzie taki, którego po przeliczeniu wychodzi wielokrotnosc surowców nablizsza liczbie10). Jako, ze projektów, których nie znamy nie mozemy “uzywac” i rozumiec, w projektach pokazujemy nazwy tychprzedmiotów, jakie faktycznie zostały uzyte w miarkach, które posiadamy. W stanie skupienia liczonym na sztuki
2.4. System metryczny 7
Alcarin Documentation, Release 0.2.6
(units) nie uzywamy miarek, ale po prostu liczby. Jednostki róznia sie rozmiarowa, znajduje to odzwierciedleniew ich opisie. Wszystkie miarki poza szczypta (wystepuje tylko w całosci) i garscia (pół garsci lub cała) moga bycprezentowane takze w przyblizonych czesciach: pełny, trzy czwarte, pół, jedna czwarta, pusty.
8 Chapter 2. Mechanika gry
CHAPTER 3
Installation instructions
3.1 Introduction
Alcarin is a complex, browser game based on ZF2 technology. Inspiration for creating it was Cantr, old, similar gamewhere characters live in more real environment.
3.2 Installation
3.2.1 Using Composer
The recommended way to get a working copy of this project is to clone the repository and use composer to installdependencies:
(The self-update directive is to ensure you have an up-to-date composer.phar available.)
In second step you should copy all “dist” configuration files to you local and reconfigure their if needed. Fastest wayon linux is:
for i in config/autoload/*.dist; do cp "$i" "${i/.dist/}"; done
Finally, if you are on UNIX system, you will probably need give change owner for you data/cache directory, for thissame like you php server use. On apache this will probably work:
sudo chown www-data data/cache
3.2.2 Persistent system
Alcarin use MongoDB as his persistent system. You should install mongo server. If you need any configuration youshould looking in config/autoload/local.php file, under the key ‘mongo’.
3.2.3 Virtual Host
Afterwards, set up a virtual host to point to the public/ directory of the project and you should be ready to go!
9
Alcarin Documentation, Release 0.2.6
3.2.4 Administration
You will probably need user with all privilages to work easy and fast. You can create one by using console script, inproject main directory:
bin/createsu [email protected] test321
First argument will be super user email address, second - password. You can use any email and password you want.
At last you should run script which will initalize mongo db instance (indexes and similar).
bin/init\ db [email protected] test321
On linux you will probably need run above commands as system administrator.
10 Chapter 3. Installation instructions
CHAPTER 4
Dev: How to?
4.1 How to define access permissions for page?
When you define new controller, nobody have access to it. You need define how kind of permissions is needed to haveaccess to page. You do it by edit “config/autoload/global.php” file - in config controllers_access -> controllers.
For sampe, assume you define new controller in admin page:
<?php
return array(...’controllers’ => array(
’invokables’ => array(...’Admin\Controller\Test’ => ’Admin\Controller\TestController’,
Now this page will be unaccessible - because all pages are unaccessible by default. You need define privilages for it.In global.php:
<?phpreturn array(...’controllers_access’ => array(
’controllers’ => array(...’Admin\Controller\Test’ => [],
By define empty array you will make this controller public accesible. To controll who have access to it, you need openCore\Permission\Resource class and define new resource type (or use exists) for you controller.
<?phpclass Resource{
...const ADMIN_TEST = 5;...public static $Descriptions = [
...’Administrative’ => [
11
Alcarin Documentation, Release 0.2.6
...Resource::ADMIN_TEST => ["Test privilage", "This is simple, test privilage."],
]
Resource::ADMIN_TEST is a constant with resource id, that must be unique resource representation (and mustbe lower than Resource::RESOURCE_LIMIT). In $Description table you define informations that are use to displayresource in player privilages admin panel (/admin/users/{id}/privilages). Now you can set this resource obligation foryou new controller:
<?phpreturn array(...’controllers_access’ => array(
’controllers’ => array(...’Admin\Controller\Test’ => [Resource::ADMIN_TEST],
Now only users with “Test privilage” option checked in privilages admin panel can request you new controller.
Remember that you can more than one resources obligation for you controller.
4.2 How to add coffee/less files to project?
First, you should prepare you guard to automatically compile LESS and COFFEE files. See there for details: Guardconfiguration.
Now, you should choose module where you shoud logically add you code. In this module you open (or create)static/coffee or static/less directory. There you can create subdirectories and put .coffee/.less files. They will beautomatically compiled - results will be stored in public/js/compiled_coffee \ public/js/compiled_less, with directoryand name exactly like original file - just with new extension - .js or .css.
Good practice is to create subdirectory with you module name in your static/coffee static/less. For sample, if youcreate new less to manage orbis editor view, you should probably use path:
{Admin module path}/static/less/Admin/orbis.less
When you end editing this file you, save it and let guard do work you can find results in
/public/css/compiles_less/Admin/orbis.css
Now you need register this new libraries in our project. Let open config/autoload/minifier.global.php file and add js/cssfile path to suitable section. Alcarin use AssetsCompiler js/css minify system. If you want learn more, read it docs.
12 Chapter 4. Dev: How to?
CHAPTER 5
Programming
Here you can found instruction about how prepare your environment to easy work with Alcarin code and what exaclyyou should know to start.
5.1 Preparing
Base introduction you can find on Installation instructions page.
Alcarin has been written in PHP language, as persistent mechanism MongoDB has been used.
If you want developing new code you should have minimum knowledge about the following technologies:
• ZF2, php framework used to create this game, if you want to learn about it there is good place to start
• MongoDB, NoSQL database system. We use mongodb-php-odm php library from colinmollenhour, it iseasy and intuitive - if you know MongoDB
• CoffeeScript, this is a little language that compiles into JavaScript. Make work with JS much easier andenjoyable
• LESS, the dynamic stylesheet language, compiling to CSS.
• TWIG, the flexible, fast, and secure template engine for PHP
• AngularJS, HTML enhanced for web apps
• Node.js, a server-side software system designed for writing scalable Internet applications, notably webservers
• socket.io, aims to make realtime apps possible in every browser and mobile device, blurring the differencesbetween the different transport mechanisms
Read about guard configuration to make you life easier with automate compile LESS, COFFEE, docs and reloadingbrowser when you make any changes in project.
13
Alcarin Documentation, Release 0.2.6
5.2 Architecture design
5.2.1 ZF2 - Alcarin Web Page
Web interface for Alcarin game - written in PHP. You can found code on github:https://github.com/psychowico/Alcarin
Note: You should have basic understand of Zend Framework 2 to read this.
We can recognize three part of application. This will be API, Web and Dev.
API
Api code should not provide any normal views, but only logic that can used to achive any action accesible in the game.It use JSON to communicate with clients. Thanks to this later we can create another client tool (for sample applicationwritten in java) to play Alcarin. All API modules should be stored in module/API directory. We use RESTful standardto write our controllers in this app part.
Web
This is the main Alcarin web page. It contains all views and use API code to call game mechanic. You can findthere specific modules - with admin, game master, guest and normal player views. In modules we have additional,not standard, .../static directory. Inside coffee and less files are store, they will be compiled to css/js and moved to/public/.. directory.
Dev
Additional code that is useful to debugging and developing application, for sample mongo panel to ZendDeveloper-Tools.
Remember to read samples code before writing anything.
5.2.2 AlcarinGameplayServer
Server application writed in Node.js and socket.io. It provide real-time event-based communication system for mainAlcarin web interface page - character page. It listening on specific port, accepting browser connections and providecommunication between logged players without database.
5.3 Guard configuration
https://github.com/guard/guard
Guard is a command line tool to easily handle events on file system modifications. If you do not want waste youtime to recompiling your coffeescript, less files, RST docs or reloading web-browser after any changes in code - it issomething that you need. You need fallow guard installation instructions. Next you should install 4 plugins:
• guard-less to automatically compiles less (like lessc –watch)
• guard-coffeescript to automatically generates your JavaScripts from your CoffeeScripts
14 Chapter 5. Programming
Alcarin Documentation, Release 0.2.6
• guard-shell to automatically runs shell commands when watched files are modified
• guard-livereload to automatically reloads your browser when ‘view’ files are modified
You will find them on guard plugins page.
If you have all installed you can simply go to Alcarin main directory and write:
guard
And it is all. All your coffeescripts, less files and docs will be automatically recompiling. If you want use livereloadtoo (auto reload browser when your make changes in files) you will probably need a browser plugin, related with youclient type. Check on this site.
5.3. Guard configuration 15
Alcarin Documentation, Release 0.2.6
16 Chapter 5. Programming
CHAPTER 6
AJAX programming
On alcarin programming process you will often need AJAX methods - because one of our objectives is creating richuser interface. Instead of default jquery ajax methods you should use one of two alcarin ajax managing ways. First isRESTful style requests, second - event style requests. Second way is prefered when you create ajax-only controllers(what you should do in most cases).
6.1 Urls
Transfering ajax targets urls by html data attributes and others html ways is trivial, awkward and time-consuming.To make it easier we just simple put static urls to global accesible urls object. You will find it in ..Al-carin\static\coffee\urls.coffee. When you need new urls for your ajax calls, just add it to this object and use anywherein code.
6.2 RESTful requests
To use RESTful requests style first you prepare default Zend Restful Controller. To make work easier, you shouldconsider using Core\Controller\AbstractAlcarinRestfulController instead of default AbstractRestfulController. It im-plement all 4 defaults restful methods, so you not must implement them all (if you need only part of it). Moreover itgive you some better errors support (in JSON mode) and two shortcuts method:
• mongo() - returing mongodb object, our wrapper for default Mongo php drivers
• gameServices() -returning GameServiceContainer instance, use with our code subsystem: Plugable game ser-vices.
To work faster with JSON responses, you should use alcarin “json()” controller plugin. Here is few samples of use it:
6.2.1 Json Example
<?php
...public function getList(){
//this same like:
17
Alcarin Documentation, Release 0.2.6
//return $this->json()->__invoke(...);//it will return jsonmodelreturn $this->json([’text’ => ’this is page information’]);
}
As long as we using AngularJS js framework to ajax calls you should use angular $resource module (for RESTrequests) or angular $http module (if you want make not-REST requests). Check their documentations for API andexamples.
18 Chapter 6. AJAX programming
CHAPTER 7
Zend Framework 2 extensions
When working with project many specific zf2 extensions has been created. They will be described here.
7.1 Controller Plugins
http://framework.zend.com/manual/2.2/en/modules/zend.mvc.plugins.html
Fast list:
• isAllowed - check that logged user is allowed to use specific $resource
• isJson - simple plugin that checking that actual request except “json” response (in ‘accept’ header)
• json - faster json responses, check this for sample: Json Example
• redirect - additional functionality for default zf2 redirect plugin
• responses - shortcut for returning non-200 html responses
• logger - plugin helpers to have easy access to logging system
7.2 View Helpers
http://framework.zend.com/manual/2.2/en/modules/zend.view.helpers.html
Fast list:
• player - return current player game object
• isAllowed - check that logged user is allowed to use specific $resource
• helpButton - auto-create dynamic help button for admin sites
• helpButton - auto-create dynamic help button for admin sites
• uri - extension for default zf2 url plugin
19
Alcarin Documentation, Release 0.2.6
20 Chapter 7. Zend Framework 2 extensions
CHAPTER 8
Plugable game services
8.1 GameServiceContainer
One of the objectives of the game engine is api divided into logical game modules. We achieve this by our Plugablegame services system. It consists of the following elements:
• GameServiceContainer - singleton class, that our plugable system heart
• GameObject - classes inherit from \Core\GameObject class
You can get GameServiceContainer from most place in our code by getting service_manager instance and use ‘game-services’ key:
<?php$game_services = $service_manager->get(’game-services’)
GameServiceContainer is lighter, faster (and less functional) version of ZF2 ServiceManager. You can use it to retrieveregistered GameObject’s. For sample:
<?php//this will get for us instance of EngineBase\GameObject\Players class.$players = $game_services->get(’players’);$logged_user = $players->current();
GameServiceContainer will load required class only when it will be needed - all services are lazy loaded.
8.2 Custom GameObjects
Often you need add you own GameObject service. For sample, you create this simple class, in hypothetical module“Test”;
<?phpnamespace Test;
class RealWorldTime extends \Core\GameObject{
public function current(){
return time();
21
Alcarin Documentation, Release 0.2.6
}}
Note that it inherit from \Core\GameObject. Now, to get this class from GameServiceContainer you need register it.It can be done in two ways - first is adding configuration key to you module.config.php file.
<?phpreturn array(
...
’game-modules’ => array(’TestModule’ => array(
’discription’ => ’Our testing module’,’game-objects’ => array(
’real-world-time’ => ’Test\RealWorldTime’,),
),),
In our example we name our module “TestModule”. Module name should be unique - or they will be merged andregard as one module. You can give any module description you want. ‘real-world-time’ is a key that you can use toretrieve you GameObject from GameServiceContainer.
You can do this same by adding getGameModuleConfig() method to any of your ‘Module’ main class. For sample:
<?phpnamespace Test;
class Module{
...
public function getGameModuleConfig(){
return array(’TestModule’ => array(
’discription’ => ’Our testing module’,’game-objects’ => array(
’real-world-time’ => ’Test\RealWorldTime’,),
),);
)
...}
Next it is simple - you can retrieve you game object by his key.
<?php//this will get for us instance of Test\RealWorldTime class.$time = $game_services->get(’real-world-time’);$current_time = $time->current();
So let go next. We want possibility to extending our game objects from another modules. So we can, for example,giving our plugin possibility to returning inner game time. We can do this by prepare next class with method thatreturning it:
22 Chapter 8. Plugable game services
Alcarin Documentation, Release 0.2.6
<?phpnamespace Test;
class RealWorldTimeExt extends \Core\GameObject{
public function current(){
//this only sample, not existed mongo table.$data = $this->mongo()->gametime->findOne([]);return $data[’current_time’];
}}
First you should note, than our GameObject extension inherit from \Core\GameObject. It is not necessery - but giveus few benefits in form of basis methods that we can use:
• mongo() - returning \Mongo_Database class, our php mongo connection
• parent() - returing this extension parent object, null if it is root GameObject
• has($ext_name) - return true, if this game object has extension with specific name
• getServicesContainer() - returning our GameServiceConteiner object
When you done writing our class you need register it in similar way like normal GameObject. You just need usediffrent key name:
<?php’game-modules’ => array(
’TestModule’ => array(’discription’ => ’Our testing module’,’game-objects’ => array(
’real-world-time’ => ’Test\RealWorldTime’,),’game-objects-ext’ => array(
’Test\RealWorldTime’ => array(’game’ => ’Test\ReadlWorldTimeExt’
),),
),),
This mean that you register Test\ReadlWorldTimeExt extension for GameObject Test\RealWorldTime and you call it“game”. Now you can use it like in this example:
<?php//this will get for us instance of Test\RealWorldTime class.$time = $game_services->get(’real-world-time’);$current_time = $time->current();$current_game_time = $time->game()->current();
If you need check game modules configuration you can retrieve it from service manager, like with all zf2 configurationentries:
<?php$game_modules_info = $service_manager->get(’config’)[’game-modules’];$test_description = $game_modules_info[’TestModule’][’discription’];echo $test_description;
8.2. Custom GameObjects 23
Alcarin Documentation, Release 0.2.6
8.3 Common services
There will described common services that can be get by GameServiceContainer. To load it call GameServiceCon-tainer get method with lowercase module name.
8.3.1 Time
Give information about game world time. Available methods:
• timestamp() - seconds from world begining
• day() - days from world begining, remember that game day is equal to four real time days
• hour() - full hour of day (0-95)
• min() - minutes of hour (0-59)
• sec() - seconds of minute (0-59)
• freeze() - freeze game time, all events will be stoped
• unfreeze() - unfreeze game time, all events will be resume
• isFreezed() - inform about game time freeze state
8.3.2 Players
Managing players. Available methods:
• current() - current player
• get($id) - specific player
Methods returns EngineBaseGameObjectPlayer objects. It provides some basic information about player.
8.3.3 Properties
Giving some global world properties. Available methods:
• radius() - game world radius
• get($key) - get specific property value
• set($key) - set specific property value
• find() - return all properties
24 Chapter 8. Plugable game services
CHAPTER 9
Logging
Logs are needed to make developing process easier and have place where you can check critical application errors infowhen you can not repeat it by youself. Zend framework 2 provide nice logging classes, you can read about it in officialzf2 manual.
In Alcarin game you can get logger class by ‘system-logger’ key.
<?php
$logger = $service_manager->get(’system-logger’);$logger->debug(’test debug message’);
...//in controllers you can use our controller log plugin:$this->log()->debug(’test debug message from controller’);
You can use all standard \Zend\Log\Logger methods, like debug, info, warn etc. To configure you local log systemyou should edit following lines in you local.php file:
<?phpreturn array(
...’logs’ => array(
’writers’ => array(’mongo-log-writer’ => array(
’service’ => ’mongo-log-writer’,’min-priority’ => Zend\Log\Logger::ERR,
),’stream’ => array(
’type’ => ’stream’,’stream’ => __DIR__ . ’/../../data/logs/alcarin.log’,’min-priority’ => Zend\Log\Logger::INFO,
),’debug-stream’ => array(
’type’ => ’stream’,’stream’ => __DIR__ . ’/../../data/logs/debug.log’,
),)
),
In this sample I added 3 logging output writers:
25
Alcarin Documentation, Release 0.2.6
• ‘mongo-log-writer’ - alcarin logger, log things to default mongo database, to “logs” table
• ‘stream’ - simple log to file, but only **information* and more priority logs
• *‘debug-stream’ - simple log to file all logs
Of course you can define you own writers, read more in zf2 docs if you want it. Remember that you php server needwrite privilages to output files.
If you work on UNIX system it would make you job easier to follow all logs in realtime. If you define loggers like insample, you can do this by use tail unix cmd.
cd /alcarin/project/dirtail -f data/logs/debug.log
26 Chapter 9. Logging
CHAPTER 10
Forms
In alcarin project we prefer using zf2 annotations form system instead of standard form system.
Alcarin code has prepared some facilities to make working with annotations forms easier. First, you should use\Core\Service\AnnotationBuilderService builder class instead of zf2 default AnnotationBuilder class. You can use itsimilar normal AnnotationBuilder:
<?php$builder = $this->getServiceLocator()->get(’AnnotationBuilderService’);$form = $builder->createForm(new \Module\Form\MyFormName());
But it give you few additional benefits:
• default form fields
• registration custom validators
• registration custom filters
10.1 Default form fields
By default AnnotationBuilderService createForm method adding default fields to any created form. It useCore\Form\DefaultFieldset class as base form. You can control this behaviour by createForm arguments:
<?php...
$submit_button_caption = ’Confirm’;$use_default_fields = true;$form_ann = new \Module\Form\MyFormName();$form = $builder->createForm($form_ann, $use_default_fields, $submit_button_caption);
10.2 Registration custom validators
It is often case that you need add some custom validators to you form. You can do this by:
27
Alcarin Documentation, Release 0.2.6
<?php...$builder->registerCustomValidator(’CheckIt’, ’Module\Validator\MyTestValidator’);...
//and in form class you now can add validator annotation:/*** @Annotation\Type("text")
* @Annotation\Validator({"name":"CheckIt"})
*/public $username;
10.3 Registration custom filters
Registration of custom filters is similar like registration of custom validators:
<?php
$builder->registerCustomFilter(’FilterIt’, ’Module\Filter\MyTestFilter’);
28 Chapter 10. Forms
CHAPTER 11
Indices and tables
• genindex
• search
29
