1. Przygotowanie rodowiska do pracy
1.1 Kompilator CC65
1.2 Microsoft Visual C++
2. Przykadowa gra
3. Katalogi i pliki
4. Terminologia
5. Jak tworzy gr
5.1 Wstp 
5.2 Budowa gry 
5.3 Pomieszczenia
5.4 Obiekty i obszary
5.4.1 Obszary
5.4.2 Obiekty
5.4.3 Referencje
5.5. Akcje
5.6. Kontenery
5.7. Obrazki i palety 
6. Pami
6.1 Manager pamici
6.2 Sprawdzanie iloci dostepnej pamici
7. Typy podstawowe i stae 
8. API
9. Narzdzia 
10.1 gfx_slicer


1. Przygotowanie rodowiska do pracy
1.1 Kompilator CC65

rodowiska opiera si na kompilatorze CC65.
Podczas pisania tego tekstu aktualna wersja kompilatora to cc65-2.13.1-1
Najprociej przygotowa rodowisko instalujc je z pliku cc65-2.13.1-1.exe z domylnymi opcjami instalacji (dodanie oczekiwanych przez kompilator zmiennych rodowiskowych CC65_INC i CC65_LIB).   
 
Nowe wersje kompilatora s tworzone z uwzgldnieniem wstecznej kompatybilnoci, ale zmianie czsto ulegaj pliki konfiguracyjne dla platform.
W przypadku problemw kompilacji w nowszych wersjach zwizanych z bdami w pliku CFG naley wykona polecenie "ld65 --dump-config atari" i zobaczy jakie s rnice w pliku CFG uywanym przez Ciebie i oczekiwanym przez kompilator.

1.2 Microsoft Visual C++

Uywanym przeze mnie IDE jest MS Visual Studio 2005 i dla tego rodowiska przygotowany jest plik projektu. rodowisko to nie jest wymagane, ale uatwia prac i kompilacj.
Do kompilacji pod Windows potrzebna jest biblioteka graficzna Allegro. Wykorzystywana wersja to 4.2.
Mam nadziej, e chtni przygotuj pliki projektw dla innych rodowisk i systemw.

2. Przykadowa gra

Gra kompilowana przez framework znajduje si w katalogu "game".
W tym katalogu domylnie znajduje si przykadowa gra. Jeeli chcesz zacz prac nad now gr, to podmie go katalogiem "empty", ktry zawiera "minimaln gr" zawierajc jedno puste pomieszczenie.
W przykadow gr warto zagra i j zachowa, eby przy tworzeniu wasnej zobaczy jak co zostao zrobione.

Przykadowa gra pokazuje jak:
1. Definiowa pokoje i przypisane im obszary
2. Definiowa obiekty i przypisane im akcje
3. Zarzdza logik akcji
4. Tworzy referencje na obiekty (tu: drzwi celi)
5. Zarzdza kontenerami (tu: beczka, inwentarz)
6. Uywa obiektw na innych obiektach
7. Obsugiwa grafik
8. Obsugiwa dwiki i muzyk
9. Obsugiwa kursor

3. Katalogi i pliki

W "engine" jest silnik gry, czyli pliki, ktrych nie trzeba zmienia przy projektowaniu gry.
W "game" jest definicja struktury gry, czyli dokadnie to, co musisz edytowa.
Plikiem kompilujcym jest "atari.bat", ktry jest woany przez rodowisko kompilacji, za plik wynikowy to "adventure.atr", czyli obraz dyskietki dla Atari.
Opis pozostaych katalogw i plikw:
"build" - zawiera pliki potrzebne do budowy pliku ATR
"debug" - tu generowane s pliki tymczasowe i wynikowe dla kompilacji pod Windows.
"doc" - opis i schemat frameworku
"tools" - narzdzia przydatne przy tworzeniu gry np. narzdzie do wycinania kawakw grafiki.
"laoo.act" to domylna paleta Atari uywana przez kompilacj dla Windows.

4. Terminologia

pomieszczenie (room) - pomieszczenie/scena/ekran gry.
obszar (area) - miejsce w pomieszczeniu, ktre mona wybra kursorem.
obiekt (object) - obiekt w grze. Kady obszar jest automatycznie obiektem.  Na obiekcie mona wykonywa akcje.
akcja (action) - podstawowa procedura, ktra jest wykonywana na obiekcie. 
kontener (container) - moe zawiera w sobie kilka obiektw. 
obrazek (picture) - definicja obrazka, ktry jest potem wywietlany 
paleta (palette) -  definicja palety, ktra jest uywana w obrazkach
referencja na obiekt - kilka obszarw moe odnosi sie do jednego obiektu. Mona w ten sposb definiowa rne ksztaty do wybrania obiektw, albo te wybiera ten sam obiekt z rnych pomieszcze. W przykadowej grze takim obiektem s drzwi celi.

Nie s wspierane aktualnie listy dialogowe i moe zostan dodane w przyszoci.

5. Jak tworzy gr
5.1 Wstp 

Tworzenie gry polega na stworzeniu definicji wszystkich elementw, ktre s wyszczeglnione w sekcji "Terminologia".
Aktualnie framework umoliwia tworzenie gier z grafik, ale nic nie stoi na przeszkodzie, by przerobi go na obsug gier czysto tekstowych.

Tworzenie gry najlepiej zacz od jej zaprojektowania (papier i dugopis jest niezastpiony). Gdy mamy rozpisane poszczeglne pomieszczenia, przeniesienie ich na komputer bdzie prostsze ni robienie tego metod prb i bdw.

Poniej zakadam, e uytkownik zna w stopniu podstawowym jzyk C.

5.2 Budowa gry 

W katalogu "game" znajduj si pliki implementacji *.c i nagwkowe *.h.
Pliki *.h powinny zawiera deklaracje (typy wyliczeniowe i deklaracje akcji) uywane w plikach *.c. 
Wszystkie pliki *.h s doczane do plikw *.c za pomoc #include "game/all_definitions.h". Ten plik naley zmodyfikowa przy dodawaniu nowych plikw *.h, ale dodawanie nowych nie jest potrzebne.

Gr mona tworzy, testowa i debugowa na PC, bo funkcje wywietlajce grafik, wypisujce tekst czy obsugujce kursor maj swoje odpowiedniki napisane z wykorzystaniem przenonej biblioteki Allegro.
Wersja na PC wykorzystuje te same elementy graficzne (MIC, DLI), co wersja dla Atari.

5.3 Pomieszczenia

Kade pomieszczenie moe mie przypisane kilka obszarw.
Oprcz obszarw posiada te trzy zdarzenia, ktrym mona przypisa akcje.
Tymi zdarzeniami s:
		
	on_room_draw - akcja wywoywana przy wejciu do pomieszczenia lub przerysowywaniu go. W niej mona np. narysowa otwarte lub zamknite drzwi po wejciu do pomieszczenia, w zalenoci od stanu drzwi.
	on_room_enter - akcja wywoywana po on_room_draw 
	on_room_exit  - akcja wywoywana przy opuszczaniu pomieszczenia 		

5.4 Obiekty i obszary

5.4.1 Obszary

Obszary s zdefiniowane w pliku game\areas\areas_def.c jako 
{pozycja_x, pozycja_y, szeroko, wysoko}
Aktualnie pozycj i wielko obszarw trzeba wpisa rcznie do tablicy na podstawie kompilacji Windowsowej.

Kady obszar ma przypisany obiekt. Jest tak, aby po klikniciu w obszar pojawio si menu kontekstowe obiektu.

5.4.2 Obiekty

Kady obiekt jest okrelony nazw i przypisanymi mu akcjami, ktre moe wybra gracz. Mog one by zmienione dynamicznie podczas gry (np. po rozmowie z winiem pojawia si opcja dania mu przedmiotu).
Kady obiekt posiada rwnie stan, ktry mona ustawi lub sprawdzi za pomoc API. Stan moe by albo wartoci liczbow z zakresu 0-127, albo flagami bitowymi (np. CLOSED|LOCKED). Podczas definiowania obiektu mona ustawi jego pocztkowy stan.
Stan obiektu jest liczb od 0-127, gdy jeden bit jest przeznaczony na informacj, czy przypisany mu obszar jest aktywny, czy nie, co mona ustawi i sprawdzi za pomoc API. 

W pliku game/objects/objects_def.c znajduj si definicje obiektw (g_objects).

UWAGA:::
Na pocztku tablicy g_objects znajduj si obiekty, ktre maj przypisane im obszary, pniej obiekty, ktre wystpuj bez obszarw.
Kady obszar gry, ktry mona wybra kursorem ma swj odpowiednik bdcy obiektem!
Poniewa g_areas[i] odpowiada obiektowi g_objects[i], z tego powodu obszary i obiekty musz by zdefiniowane w tej samej kolejnoci!
:::UWAGA

Otwrz plik przykadowej gry game/areas/areas_def.h
Jak widzisz, s tam w kolejnoci wyliczone obiekty, majce swoje obszary.
To wyliczenie odnosi si zarwno do obiektw w game\objects\objects_def.c jak i obszarw zdefinowanych w game\areas\areas_def.c

Elementw w g_objects[] moe by wicej ni elementw w g_areas[] - te obiekty s na przykad pochowane w kontenerach, a nie stanowi klikalnych obszarw pomieszcze.
  
Obiekty nie posiadajce obszarw s wyliczone w game\objects\objects_def.h i numer pierwszego zaczyna si od AREA_LAST_AREA, czyli po obiektach "obszarowych".

5.4.3 Referencje

Jak zostao powiedziane wczeniej, kady obszar ma przypisany obiekt. Jest tak, aby po klikniciu w obszar pojawio si menu kontekstowe obiektu.
Co zrobi w przypadku, gdy jeden obiekt powinien mie przypisane dwa obszary (lub wicej), aby by na przykad dostp do tych samych drzwi z kilku pomieszcze? Do tego zostay stworzone referencje.
Jeeli w definicji obiektu jego nazw ustalimy na TEXT_NONE (inaczej NULL), to stan obiektu (variable) naley ustali na obiekt, do ktrego ten obszar w rzeczywistoci si odnosi.
W przykadowej grze referencj na obiekt OBJECT_CELL_DOOR stanowi OBJECT_HALL_CELL_DOOR_REF. 

5.5 Akcje

Wszystkie akcje s zadeklarowane w game\actions\actions.h i tam naley je dodawa w miar potrzeby.
Implementacj najwygodniej podzieli wedug pomieszcze (*.c), poniewa akcji moe by duo. Jest to bardziej czytelne i przyspiesza kompilacj, ale dodanie kolejnego pomieszczenia wymaga dodania kolejnego pliku do skryptu kompilacji.
Jeeli uwaacie, e czytelniejsze jest wrzucenie wszystkiego do jednego pliku, to d ajcie zna.

5.6 Kontenery

Kontenery umoliwiaj przechowywanie w nich obiektw.
Kady kontener ma swoj nazw oraz tablic obiektw, ktre ma w rodku.
Przykadowym kontenerem, jest inwentarz gracza.
Na obiektach w kontenerze mona wykonywa akcje.

Poniewa kontener zawiera obiekty posiadajce reprezentacj graficzn, konieczne jest zrobienie mapowania obiektw na obrazki. Suy do tego tablica g_picture_object_mapping w pliku game\pictures\pictures_def.c 

5.7 Obrazki i palety

Adventure Studio obsuguje pliki MIC i DLI. Pliki MIC s standardowym zrzutem pamici ekranu w gr. 15. Pliki DLI zawieraj informacj o kolorach w linii.
Pliki DLI s generowane przez doczone narzdzie gfx_slicer.

Obrazki i palety naley zdefiniowa w pliku game\pictures\pictures_def.c, najprociej na podstawie informacji wygenerowanych przez gfx_slicer.
Jeeli dla obrazka paleta jest zdefiniowana jako PALETTE_NONE, to nie jest ona zmieniana w liniach przy rysowaniu obrazka.  
 
6. Pami

Silnik gry ma ~10KB, pami ekranu to 8KB. 
Na gr wraz z grafik i dwikiem dostpne jest okoo 27KB pamici, co w zalenoci od liczby tekstw pozwala na stworzenie gry majcej nawet kilkanacie pokoi.
Obrazki wczytywane s do pamici dynamicznie i zawsze musi by pozostawione co najmniej tyle bajtw wolnej pamici, ile ma najwikszy obrazek.
Pami "pod ROMem" jest ju w czci wykorzystywana przez framework (duszki, paleta).

Wielko wikszoci tablic jest ustalana dynamicznie podczas definiowania typw wyliczeniowych (XXXX_LAST_xxxx np. ROOM_LAST_ROOM), ale cz trzeba ustali w config.h (MAX_xxxx).
Nie warto ustala wicej ni potrzeba, bo zabiera to pami.

W miar moliwoci naley ograniczy uywanie skomplikowanych funkcji jzyka C np. sprintf, poniewa ich implementacja zabiera duo pamici.

6.1 Manager pamici

W silniku wystpuje prosty manager pamici, ktry zwalnia pami najdawniej wczytywanych obrazkw i palet.
Uytkownik nie musi zajmowa si wczytywaniem obrazkw czy ich palet, bo jest to robione automatycznie wedug definicji. 

6.2 Sprawdzanie iloci dostepnej pamici

Warto co jaki czas sprawdza ilo pozostaej pamici.
Najprociej doda globaln tablic:
unsigned char mem_test[50000]; 
Kompilator powinien wypisa co w stylu:
"Memory area overflow in `RAM', segment `BSS' (36847 bytes)""
Znaczy to, e zostao Ci 50000 - 36847 = 13153 bajtw pamici na program.

Poczytaj o kompilatorze CC65, bo jest on specyficzny i ma rne ograniczenia.

7. Typy podstawowe i stae

// Podstawowe
typedef unsigned char byte;
typedef unsigned int word;
typedef unsigned char bool;
#define true 1
#define false 0

// Akcje
typedef void (*action_function)(void);
#define ACTION_NONE 0

// Obszary
#define AREA_ACTIVE 0 
#define AREA_INACTIVE 0x80
#define AREA_NONE 0xFF

// Teksty
#define TEXT_NONE 0

// Kontenery 
typedef byte container_id;
typedef byte container_iterator; 
#define CONTAINER_NONE 0xFF
#define CONTAINER_ITERATOR_NPOS 0xFF

// Obiekty
typedef byte object_id;
#define OBJECT_NONE 0xFF

// Obrazki i palety
typedef byte picture_id;
typedef byte palette_id;
#define PICTURE_NONE 0xFF
#define PALETTE_NONE 0xFF

// Pomieszczenia
typedef byte room_id;
#define ROOM_FIRST 0
#define ROOM_NONE 0xFF

8. API

// Konsola

void console_wait_for_fire(void);
void console_clear(void);
void console_print(unsigned char *s, bool wait);

// Pomieszczenia

room_id room_current_get(void);
void room_current_set(room_id new_room);

// Obiekty 

byte object_value_get(object_id obj);
void object_value_set(object_id obj, byte value);
bool object_flags_check  (object_id obj,  byte flags);
void object_flags_set  (object_id obj,  byte flags);
void object_flags_zero (object_id obj,  byte flags);

void object_action_replace(object_id obj, action_function old_function, action_function new_function, char *new_name);
char *object_name_get(object_id obj);
void object_name_set(object_id obj, char *new_name);

object_id object_get_through_references(object_id obj);

// Obszary

void area_activity_on(object_id ar);
void area_activity_off(object_id ar);
bool area_activity_check(object_id ar);

// Obrazki

void picture_draw(picture_id pic, byte pos_x, byte pos_y);

// Obrazki (dodatkowe, nie potrzebne raczej do wolania, bo robi wszystko picture_draw)
bool picture_load(picture_id pic);
picture_id picture_get_from_object(object_id obj);
bool palette_load(palette_id);
void palette_set(palette_id pal, byte pos_y);
void palette_zero(byte start_y, byte end_y);
void palette_generate_dli(void);

// Akcje
void action_call(action_function act); // mona te wywoa po nazwie 

// Kontenery

container_iterator container_find(container_id conatainer, object_id to_find);
object_id container_get(container_id conatainer, container_iterator obj_number);
object_id container_remove(container_id conatainer, container_iterator to_remove);
container_iterator container_insert(container_id conatainer, object_id to_add);
byte container_get_number_of_items(container_id conatainer);
object_id container_object_move_with_choose(container_id source, container_id destination);
object_id container_merge(container_id container, object_id to_remove1, object_id to_remove2, object_id new_object); 

9. Odczyt i zapis gry

Aktualnie nie jest wspierany.

Jeeli tworzc gr bdziesz wykorzystywa jedynie udostpnione API i nie bdziesz definiowa dodatkowych zmiennych, a operowa na obiektach, to zapis i odczyt mona zrobi banalnie zapisujc i wczytujc tablice definicji gry.

10. Narzdzia 
10.1 gfx_slicer

gfx_slicer to narzdzie do wycinania elementw grafiki. Pracuje na plikach MIC i COL, ktre obsuguje te Graph2Font. 
Poniewa w tych plikach nie ma zapisanej ich wielkoci, to trzeba jako parametry przy uruchomieniu poda szeroko i wysoko obrazka w pikselach. Dla plikw MIC i COL wygenerowanych przez Graph2Font jest to 160 i 240. 

Po uruchomieniu obszar obrazka wybieramy lewym klawiszem, za prawym zrzucamy go do pliku. Wybieranie dziaa na siatce 4x1, poniewa w 1 bajcie kodowane s 4 kolejne piksele.
gfx_slicer tworzy dla zrzuconych obszarw pliki bmp (podgld), MIC i DLI.
Plik DLI to informacja o palecie, ktra jest wykorzystywana przez Adventure Studio. Paleta DLI jest zapisana w sposb bardziej zwizy ni COL.

Wygenerowane pliki graficzne maj nazw:
oryginalna_nazwa.pozycja_x,pozycja_y (szeroko, wysoko)
Jest to przydatne do definiowania obrazkw i obszarw.