Alcarin Documentation
Transkrypt
Alcarin Documentation
Alcarin Documentation Release 0.2.6 psychowico December 28, 2013 Contents 1 Alcarin - Opowieść (pl) 1.1 Świat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2 Życie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3 3 2 Mechanika gry 2.1 Czas . . . . . . . 2.2 Zwykli gracze . . 2.3 Substancje . . . . 2.4 System metryczny . . . . 5 5 6 6 7 3 Installation instructions 3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 9 9 4 Dev: How to? 4.1 How to define access permissions for page? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2 How to add coffee/less files to project? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 11 12 5 Programming 5.1 Preparing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2 Architecture design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3 Guard configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 13 14 14 6 AJAX programming 6.1 Urls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2 RESTful requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 17 17 7 Zend Framework 2 extensions 7.1 Controller Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.2 View Helpers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 19 19 8 Plugable game services 8.1 GameServiceContainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.2 Custom GameObjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 21 21 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i 8.3 9 Common services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logging 24 25 10 Forms 10.1 Default form fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.2 Registration custom validators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.3 Registration custom filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 27 27 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 I developing this project myself - sorry! Contents: Contents 1 Alcarin Documentation, Release 0.2.6 2 Contents CHAPTER 1 Alcarin - Opowieść (pl) Narazie wrzuc˛e tutaj troch˛e opisu świata gry i luźno powiazanych ˛ myśli, ta cz˛eść b˛edzie ważniejsza w przyszłości. 1.1 Świat Świat w Alcarin nie przypomina naszej planety. Jest mieszanka˛ mitologii indyjskiej, ksia˛żek Tolkiena, Pratchett’a i innych. Planeta ma kształt dysku, opiera si˛e o plecy czterech słonii, które stoja˛ na wielkich żółwiu pływajacym ˛ w przestrzeniach wszechświata. Światło i ciepło planecie daje olbrzymia latarnia znajdujaca ˛ si˛e na szczycie wielkiej kolumny postawionej przez bogów w centrum świata. Latarnia ta pulsuje, tak że mamy atmosfer˛e podobna˛ do naszego dnia i nocy. Jednak dzień trwa dwie nasze doby (48h), tak samo jak i noc. Z tego wynika, że pełny obrót latarnii zajmuje jej 4 doby czasu naszego świata. Na planecie nie ma wyraźnych pór roku, za to sa˛ obszary znacznie różniace ˛ si˛e klimatem - na obrzeżach planety panuje wieczne zlodowacenie (dzi˛eki temu oceny nie “spływaja”), ˛ za to w okolicach centrum mamy coś w rodzaju tropikalnej dżungli. 1.2 Życie 1.2.1 Rośliny W świecie magii i pradawnych mocy czasem trudno określić, co jest roślina˛ a co zwierz˛eciem. Nie zdziw si˛e jeśli b˛edzie zmuszony uciekać gdy w trakcie polowania spotkasz gigantyczne drzewo, któremu nie spodoba si˛e twoje towarzystwo. 1.2.2 Zwierzeta ˛ Niektóre zwierz˛eta na tej planecie sa˛ odpowiednikiem żyjacych ˛ na ziemi, jednak spotkać można tam też wiele nieznanych nam istot. Zwierz˛eta potrafia˛ si˛e rozmnażać i czasem podróżować, ich aktywność (i co za tym idzie przykładowo szansa upolowania, albo niesione zagrożenie) może różnić si˛e zależnie od tego, czy trwa noc, czy też dzień. 1.2.3 Humanoidy Na Alcarin można spotkać wi˛ecej niż jeden typ intelegintnych istot. Na pewno b˛eda˛ to elfy, krasnolodu i ludzie, jednak być może potem znajdzie si˛e tego wi˛ecej. 3 Alcarin Documentation, Release 0.2.6 1.2.4 Nadprzyrodzone Alcarin to świat magii i bogów. Chodź nie zdarza si˛e to cz˛esto, czasem można spotkać istoty wszechpot˛eżne, których moc wydaje si˛e pochodzić od bóstw. Czasem niosace ˛ groz˛e, innym zaś razem ukojenie. 4 Chapter 1. Alcarin - Opowieść (pl) CHAPTER 2 Mechanika gry 2.1 Czas Pełen cykl dobowy b˛edzie trwał 24 * 4 = 96 godzin. Czyli dzień b˛edzie trwał dwie nasze doby, po którym nastapi ˛ noc, trwajaca ˛ podobnie. Wszelkie wystapiania ˛ słowa “dzień” poniżej odnosza˛ si˛e do dnia świata gry. W grze istnieje absolutny czas, zgodny w każdym fragmencie świata (z dokładnościa˛ do sekundy). Możemy także określić czas lokalny - to jest zależny od pozycji w przestrzeni. Jest przydatny przykładowo przy obliczaniu oświetlenia. Godziny liczymy od 0 do 96, ale w świecie używamy określeń od 0 do 24 dniowa i od 0 do 24 nocna. 2.1.1 Współrzedne ˛ Świat używa kartezjańskiego systemu współrz˛ednych o odbitej osi Y, z punktem (0, 0) w centrum świata. Czyli Y rośnie w dół mapy, X rośnie w jej prawa˛ stron˛e. 2.1.2 Oświetlenie Świat Alcarin jest oświetlany przez Wielka˛ Latarni˛e (Great Lighthouse) postawiona˛ w jego centrum poprzez bogów. Latarnia jest umiejscowiona na olbrzymim tworze skalnym o prawie płaskich ścianach, o wysokości około 5 kilometrów i szerokości przy podstawie około jednego kilometra. Jest także źródłem ciepła - tereny położone najbliżej jej przypominaja˛ okolice równikowe na Ziemi - zaś ziemie położone najdalej - Antarktyd˛e. Wielka Latarnia cyklicznie pulsuje, świecac ˛ przez 48h i gasnac ˛ na kolejne 48h - tworzac ˛ w ten sposób system dobowy. Pory Dnia Godzin˛e 0 uznajemy za poczatek ˛ dnia. Latarnia wtedy si˛e rozgrzewa, zaczyna robić si˛e jasno. Pory prezentuja˛ si˛e nast˛epujaco: ˛ • od 44N.(nocnej) do 4D.(dziennej) mamy poranek • od 4D. do 44D. mamy pełni˛e dnia (pełne oświetlenie) • od 44D. do 4N. mamy wieczór • od 4N. do 44N. mamy noc (praktyczny brak oświetlenia) 5 Alcarin Documentation, Release 0.2.6 2.2 Zwykli gracze Zwykły gracz może stworzyć do 3 postaci. Sa˛ dwie możliwości powstania postaci: • zamieszkanie w ciele 5-letniego dziecka (wymaga istnienia takie dziecka w świecie, prawdopodbnie b˛edzie si˛e wiazała ˛ z długim oczekiwaniem) • przebudzenie si˛e postaci w wieku 20 lat, w jakiś fabularny sposób, zależnie od rasy Postacie żyja˛ normalnie około 90 dni, po czym zaczynaja˛ si˛e starzeć. W wieku 140 dni sa˛ już zupełnie słabi i podatni na wszelkie słabości, moga˛ zginać ˛ od zadrapań etc. Gdyby jakaś postać dożyła 200 dni, od tej granicy codziennie ma 5% szans na naturalna˛ śmierć. Konsekwencja˛ starzenia jest osłabienie wszelkich zdolności(szczególnie siły fizycznej) jednak z pami˛etanym “najwyższym” poziomem i możliwościa˛ 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łaściwości określajacy ˛ możliwość interakcji obiektu ze światem, jak jego palność, wytrzymałość, czy twardość. Od tego zależy, jak dobrze b˛edzie si˛e palił dany obiekt etc. • źródło - abstrakcyjne poj˛ecie określajace ˛ zbiór substancji jakie moga˛ być pozyskiwane. źródła przypisuje si˛e do określonych obszarów Stwierdziliśmy, że wszelkie używalne surowce jak i szeroko rozumiane narz˛edzia b˛eda˛ należeć do tej samej grupy substancji. Można je uzyskać na jeden z dwóch sposobów: pozyskać ze źródła, lub wyprodukować (prawdopodobnie przy użyciu innych substancji i narz˛edzi). Substancje charakteryzuja˛ si˛e nast˛epujacymi ˛ właściwościami: • nazwa (name) - unikalna nazwa bazowa substancji (np. hammer) • etykieta(label) - tłumaczalny ciag ˛ używany do wygenerowania nazwy substancji w grze, z użyciem jej głównego składnika (np. “{{material}} młotek”) • opis(description) - słowny opis wygladu ˛ i podstawowych właściwości substancji • stan skupienia(state of matter) - stan skupienia materii, jeden z czterech: – gazowy(gas) - przenoszony jedynie w dedykowanych pojemnikach, samoczynnie po prostu rozpływa si˛e w powietrzu – ciekły(liquid) - przenoszony w wi˛ekszości pojemników, samoczynnie rozlewa si˛e i zatraca – sypki(powder) - może leżeć na ziemi w dowolnej ilości, zmienny kształt – sztuki(units) - jako jedyny liczony w sztukach, a nie w pojemnikach (czyli niedoszacowanej obj˛etości, sprawdź dokument “System metryczny”); może leżeć na ziemi i być noszony w pojemnikach, cz˛esto duża obj˛etość wzgl˛edem masy • cechy(properties) - zbiór właściwości określajacy ˛ możliwość interakcji obiektu ze światem, jak jego palność, wytrzymałość, czy twardość. Od tego zależy, jak dobrze b˛edzie si˛e palił dany obiekt etc. Obiekty pozyskiwane ze źródeł przyjmuja˛ wartość tych właściwość zależnie od ustawień źródła. Obiekty tworzone przez postacie zyskuja˛ je domyślnie przy pomocy obliczania średniej ważonej substancji użytych przy wytwarzaniu danego obiektu. Jednak ka˛żda˛ z wartości cech konkretnej substancji można nadpisać własnym wzorem, używajacym ˛ wszelkich innych cech tej substancji. 6 Chapter 2. Mechanika gry Alcarin Documentation, Release 0.2.6 • jakość(quality)- jakość jest specjalnym typem cechy. Charakteryzuje si˛e tym, że domyślnie nie jest obliczana jedynie przy użyciu średniej ważonej jakości użytych substancji, ale także przy uwzgl˛ednieniu staranności pracy, umiej˛etności rzemieślnika, jakości użytych narz˛edzi. Jako źródło substancji rozumiemy abstrakcyjny zestaw informacji który może być wykorzystany do wygenerowania określonych substancji z określonymi cechami(jak jakość, palność), o określonymi bogactwie etc. Źródła składaja˛ si˛e z listy generowanych substacji (cz˛esto jednej). Samo źródła posiada jedynie podstawowe właściwości: • etykieta(label) - domyślny tłumaczalny ciag ˛ używany do wygenerowania nazwy źródła substancji w grze (np. “Las”, “Kopalnie”). Postacie powinny mieć możliwość zapami˛etywania własnej nazwy dla każdej instancji źródła • opis(description) - krótki opis fabularny źródła Każdy z wpisów na liście substancji charakteryzuje si˛e nast˛epujacymi ˛ właściwościami: • substancja (resource) - po prostu wcześniej przygotowany typ substancji • bogactwo(richness) - podana jako sumaryczna dost˛epna masa tuż po stworzeniu zasobu • odnawialność(recovery) - z jaka˛ szybkościa˛ źródło b˛edzie si˛e odnawiać przy pozostawieniu odłogiem - może być to wzór wykorzystujacy ˛ inny współczynnik (tak, by po zupełnym wykarczowaniu lasów na danym obszarze praktycznie przestały odrastać, etc. ) • cechy(properties) - zakresy cech substancji (także jako wzory) jakie moga˛ zostać otrzymane z tego źródła Instancja źródła(source instance) wyróżnia si˛e od typu źródła posiadaniem informacji o stopniu zużycia każdej z generowanych substancji. 2.4 System metryczny Mierzenie wszystkich wag w dokładnych wartościach masy - np. w gramach, jak w Cantrze, jest nienaturalne i powoduje różne głupie sytuacje w grze. Ogranicza ludziom wyobraźni˛e dokładnościa,˛ uniemożliwia oszukiwanie itp. Postanowiliśmy, że nasz system powinien charakteryzować sie nast˛epujacymi ˛ cechami: • brak konieczności używania dokładnej ilości zasobów • brak stałej, dokładnej jednostki metrycznej (ze strony graczy) - zamiast tego używanie rozmaitych miarek bazowo “szczypty” i “garści” (potem innych pojemników) • niedokładność miarek - zależnie od dokładności wykonania ten sam typ kubka może różnić si˛e obj˛etościa˛ • po stronie serwera wszelkie instancje pojemników maja˛ tak określona˛ pojemność (obj˛etość), jak i określona˛ ilość masy jaka˛ moga˛ pomieścić. w wielu przypadkach b˛edzie to bardzo duża masa i faktyczne znaczenie b˛edzie miała obj˛etość Szczegóły: • istnieja˛ dwie typy naturalnych miarek: szczypta i garść • każda postać ma troch˛e inna˛ garść/szczypt˛e • szczypta to ( 4ml +/- 25%, czyli 3ml-5ml ) stała dla postaci • garść to ( 100ml +/- 15%, czyli 85ml-115ml ) stała dla postaci Osoba b˛edzie widziała zasoby w swoim inwentarzu, czy w otoczeniu poprzez najlepiej dopasowany pojemnik jaki ma w plecaku (niech to b˛edzie taki, którego po przeliczeniu wychodzi wielokrotność surowców nabliższa liczbie 10). Jako, że projektów, których nie znamy nie możemy “używać” i rozumieć, w projektach pokazujemy nazwy tych przedmiotów, jakie faktycznie zostały użyte w miarkach, które posiadamy. W stanie skupienia liczonym na sztuki 2.4. System metryczny 7 Alcarin Documentation, Release 0.2.6 (units) nie używamy miarek, ale po prostu liczby. Jednostki różnia˛ si˛e rozmiarowa,˛ znajduje to odzwierciedlenie w ich opisie. Wszystkie miarki poza szczypta˛ (wyst˛epuje tylko w całości) i garścia˛ (pół garści lub cała) moga˛ być prezentowane także w przybliżonych cz˛eściach: 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 game where 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 install dependencies: (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 way on 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 this same 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 you should 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, in project 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 have access 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: <?php return 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 open Core\Permission\Resource class and define new resource type (or use exists) for you controller. <?php class 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 must be lower than Resource::RESOURCE_LIMIT). In $Description table you define informations that are use to display resource in player privilages admin panel (/admin/users/{id}/privilages). Now you can set this resource obligation for you new controller: <?php return 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: Guard configuration. 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 be automatically compiled - results will be stored in public/js/compiled_coffee \ public/js/compiled_less, with directory and 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 you create 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/css file 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 exacly you 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 is easy and intuitive - if you know MongoDB • CoffeeScript, this is a little language that compiles into JavaScript. Make work with JS much easier and enjoyable • 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 web servers • socket.io, aims to make realtime apps possible in every browser and mobile device, blurring the differences between the different transport mechanisms Read about guard configuration to make you life easier with automate compile LESS, COFFEE, docs and reloading browser 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 https://github.com/psychowico/Alcarin - written in PHP. You can found code on github: 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 application written in java) to play Alcarin. All API modules should be stored in module/API directory. We use RESTful standard to 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 find there 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 ZendDeveloperTools. 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 main Alcarin web interface page - character page. It listening on specific port, accepting browser connections and provide communication 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 you time to recompiling your coffeescript, less files, RST docs or reloading web-browser after any changes in code - it is something 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 livereload too (auto reload browser when your make changes in files) you will probably need a browser plugin, related with you client 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 rich user interface. Instead of default jquery ajax methods you should use one of two alcarin ajax managing ways. First is RESTful 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 ..Alcarin\static\coffee\urls.coffee. When you need new urls for your ajax calls, just add it to this object and use anywhere in code. 6.2 RESTful requests To use RESTful requests style first you prepare default Zend Restful Controller. To make work easier, you should consider using Core\Controller\AbstractAlcarinRestfulController instead of default AbstractRestfulController. It implement all 4 defaults restful methods, so you not must implement them all (if you need only part of it). Moreover it give 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 services. 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 jsonmodel return $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 REST requests) or angular $http module (if you want make not-REST requests). Check their documentations for API and examples. 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 Plugable game 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 ‘gameservices’ 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 retrieve registered 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”; <?php namespace 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. <?php return 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 and regard as one module. You can give any module description you want. ‘real-world-time’ is a key that you can use to retrieve you GameObject from GameServiceContainer. You can do this same by adding getGameModuleConfig() method to any of your ‘Module’ main class. For sample: <?php namespace 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 that returning it: 22 Chapter 8. Plugable game services Alcarin Documentation, Release 0.2.6 <?php namespace 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 give us 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 use diffrent 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 configuration entries: <?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 GameServiceContainer 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 info when you can not repeat it by youself. Zend framework 2 provide nice logging classes, you can read about it in official zf2 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 system you should edit following lines in you local.php file: <?php return 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 need write 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 in sample, you can do this by use tail unix cmd. cd /alcarin/project/dir tail -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 it similar 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. Core\Form\DefaultFieldset class as base form. You can control this behaviour by createForm arguments: It use <?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