 __________________________________
|\________________________________/d
| |                              |o8
| |  PPPPPPPP AAAAAAAA GGGGGGGG  |88
| |  PPP  PPP AAA  AAA GGG       |88
| |  PPPPPPPP AAAAAAAA GGG GGGG  |88            per Pancake / CatHack!
| |  PPP      AAA  AAA GGG  GGG  |88
| |  PPP      AAA  AAA GGGGGGGG  |88
| |______________________________|88
|/d8888888888888888888888888888888\8

       ------------------------
         Portable Arcade Game
       ------------------------

  .-----------------------------------------------------.
.-'-----.                                               |
| Index |                                               |
`-,-----'    .------ Introduccio [1]                    |
 |_________.'                                           |
 |           .------ Utilitzacio [2]                    |
 |_________.'                                           |
 |            .----- Format .PAG [3]                    |
 |-----------'                                          |
 |            .----- Col.laboracio [4]                  |
 |-----------'                                          |
 |                                                      |
 `------------------------------------------------------'



 [1]

 ---------------
   INTRODUCCIO
 ---------------


PAG, es un joc que preten començar a fomentar un petit estandar dins dels
jocs de plataformes, aquest estandar es marcat per fitxers en ascii,
realitzables amb qualsevol editor.

Llavors, seguint unes simples normes es poden crear infinitat de pantalles,
enllaçant-les entre elles, creant objectes mobils, i amb totes les
caracteristiques tipiques dels jocs de plataformes (amb certes limitacions).

Aquestes limitacions son ben clares ja que estem parlant d'una entrada
ascii, que busca la facilitat de creacio i no possibilitats, aixi que
podrem crear pantalles de manera simple i rapida.

PAG, es un simple interpret d'aquests fitxers en format .PAG. Logicament, es
poden crear nous interprets que utilitzin de les caracteristiques de les
AA-LIB, o d'altres llibreries grafiques per visualitzar el joc de forma
més grafica.

L'objectiu d'aquest projecte és el de crear un petit estandar per a un joc de
plataformes, i que d'aquesta manera es puguin crear nous interprets, pero
mantenint sempre les compatibilitats amb les pantalles creades en ASCII.





 [2]
 
---------------
  UTILITZACIO
---------------

L'utilitzacio del joc, es ben simple, abans de tot hem de preparar la
terminal per jugar...per fer aixo caldran dos pasos basic, el primer
es el de definir el kbdrate, es a dir el temps d'espera entre tecla i
tecla, d'aquesta manera ens podrem moure de manera senzilla sense cap
problema. Aixo es fa aixi:

	$ kbdrate -r 30

30 es el valor optim, encara que va a gustos :)

L'altre punt a destacar es que les tecles definides per defecte requereixen
que estigui possat el bloqnum, o el bloqFN (en portatils :), aixi que no
ens espantem pq les tecles per defecte son del keypad:

             ESQUERRA  VERTICAL*   DRETA
           +----------+----------+-------+
DOBLE SALT |    7     |    8     |   9   |
           +----------+----------+-------+
      SALT |    4     |    5     |   6   |
           +----------+----------+-------+
      ---- |    1     |    2     |   3   |
           +----------+----------+-------+

*VERTICAL= 8 i 5 son cap amunt i 2 es cap abaix.

Altres problemes amb la terminal...

En principi no controla el nombre de linies de la terminal, aixi que potser
en algunes terminals no es vegi be, i tp s'aprofiti del tot en d'altres,
aixi q esperem a la proxima versio, q estara escrita en aalib enlloc de
ncurses, i ja podrem controlar millor totes aquestes variables, al igual
q aprofitare les funcions malloc per fer-lo mes adaptable i fent scroll.

Un cop tinguem tot preparat ja podem entrar al joc, per cargar la pantalla
podem fer-ho de diverses maneres. Pero primer de tot mireu l'ajuda:

	$ pag --help

Llavors alla ja ens ho diu clar, simplement haurem de fer una cosa, muntar
com a primer argument el nom del fitxer, directori o paquet de nivells que
vulguem carregar:

FITXER: Carrega el fitxer, no fa chdir, aixi q si hi han mes nivells seguits
        d'aquest no podra carregar-los.
        exemple.
          $ /usr/games/pag $HOME/map.pag

DIRECTORI: Carrega el fitxer 001.pag del directori indicat:
        exemple.
          $ /usr/games/pag $HOME/maplevel/

PAQUET: Els paquets de nivells es carreguen de la mateixa manera que els
        directoris, encara que estan situats a /usr/share/games/pag/levels
        exemple.
          $ /usr/games/pag paquetlevel



 [3]

----------------
  FORMAT .PAG:
----------------
Aquest format és el que defineix el format de les pantalles del joc. Es
poden editar amb un editor qualsevol, i en principi (en la versio 0.X del
joc) nomes permet editar pantalles amb marges de 80x22.

Abans de fer la pantalla (o entre mig...pero sempre queda millor al principi :)
es recomenable escriure un seguit de comentaris que seran interpretats per
l'interpret per modificar la seva conducta, es a dir, gracies a aquestes
ordres poden ser configurats certs aspectes de l'entorn.

#ver=<nombre>

Aquest comentari serveix per definir la versio de l'interpret de pantalles
( no el representador grafic ) que es necessita per poder-se obrir correctament
la pantalla. Si el client te una versio inferior al nombre definit no cargara
la pantalla (o ho deixara a tria de l'usuari (encara no va aixo)), ja que pot
ser mal interpretada per culpa d'errors i demes.
    exemple: #ver=0





A l'hora d'editar la pantalla, cal tenir en compte diversos caracters,
els quals ens permetran introduir elements al mapa.

 ____________________________________________________________________
| caracter                       definicio                           |
|-----------.                                                        |
|           | BLOC:                                                  |
|     #     |    Simbolitza un bloc de paret o de terra, aquests     |
|           |    blocs delimiten el moviment de l'usuari.            |
|           |--------------------------------------------------------|
|           | AIGUA:                                                 |
|           |    Amb el signe (alt+126), definim que en aquell       |
|     ~     |    quadre hi ha aigua, amb la conseqüent modificacio   |
|           |    del moviment de l'usuari.                           |
|           |--------------------------------------------------------|
|           | INICI:                                                 |
|           |    Indica que aquell punt sera un dels punts d'inici   |
|           |    de l'usuari, n'hi poden haver fins a 10. Pero és    |
|     A     |    necessari que n'hi hagi com a minim 1. Si quan      |
|           |    carreguem la pantalla no indiquem a quina posicio   |
|           |    volem començar, l'interpret ens donara a escollir.  |
|           |--------------------------------------------------------|
|           | PUNT DE PAS:                                           |
|     P     |    Quan es pasa per davant d'una 'P' que simbolitza    |
|           |    una bandera, l'interpret ho memoritza, i si ens     |
|           |    maten tornarem a començar des d'aqui.               |
|           |--------------------------------------------------------|
|           | TERRA MECANIC:                                         |
|     >     |    Quan l'usuari passa per damunt d'un d'aquests       |
|     <     |    signes, aquest sera desplaçat directament cap a     |
|           |    la dreta o l'esquerra respectivament.               |
|           |--------------------------------------------------------|
|     ,     | PUES:                                                  |
|     '     |    Quan l'usuari toqui una pua (apostrof o coma),      |
|           |    sera directament eliminat i perdrà una vida.        |
|           |--------------------------------------------------------|
|     \     | TERRA INCLINAT:                                        |
|     /     |    Si l'usuari pasa per sobre d'un terra inclinat,     |
|           |    aquest relliscarà i caura progresivament. També     |
|           |    pot ser utilitzat per modificar les trajectories    |
|           |    de les plataformes mobils.                          |
|           |--------------------------------------------------------|
|     .     | PUNTS:                                                 |
|     o     |    Els punts ens permeten aconseguir mines per         |
|           |    poder-les llençar contra els enemics. 5 punts       |
|           |    equival a una mina.                                 |
|           |            .   ->   1 punt                             |
|           |            o   ->   5 punts                            |
|           |--------------------------------------------------------|
|     z     | MOLLES:                                                |
|     Z     |    Les molles ens permeten saltar per arribar més      |
|           |    amunt, la 'z' significa un salt de valor 5. i la    |
|           |    'Z' significa un salt de valor 10.                  |
|           |--------------------------------------------------------|
|     ^     | ASCENSOR:                                              |
|           |    Quan l'usuari es posa sobre una peça d'aquestes,    |
|           |    sera propulsat directament 1 punt cap amunt. És     |
|           |    Impossible baixar per aquests llocs.                |
|           |--------------------------------------------------------|
|     H     | ESCALA:                                                |
|           |    L'usuari pot pujar i baixar per aquestes escales.   |
|           |    quan aquestes estan en horitzontal, l'usuari es     |
|           |    penja per sota avançant amb els braços.             |
|           |--------------------------------------------------------|
|     @     | VIDA:                                                  |
|           |    Quan l'usuari passi per sobre, rebrà una vida.      |
|           |--------------------------------------------------------|
|           | ENEMIC:                                                |
|     x     |    Aquests son els enemics que en principi poblaran    |
|           |    les nostres pantalles, es mouen horitzontalment.    |
|           |--------------------------------------------------------|
|     +     | TRONC:                                                 |
|           |    Un terra fet amb troncs (pont) pot ser traspassat   |
|           |    ambdues direccions.                                 |
|           |--------------------------------------------------------|
|     -     | TERRA CAIENT (falling ground :)                        |
|           |    Quan passes per sobre d'aquest pont, les peces      |
|           |    d'aquest s'aniran desmuntant i caient.              |
|           |--------------------------------------------------------|
|     d     | MOLLES HORITZONTALS:                                   |
|     b     |    Aquestes molles t'empenyen en sentit horitzontal    |
|           |    es a dir, la 'd' cap a l'esquerra i la 'b' cap a    |
|           |    la dreta.                                           |
|           |--------------------------------------------------------|
|     ?     | OXIGEN:                                                |
|           |    Els interrogants, es a dir, fonts d'oxigen ens      |
|           |    permeten aguantar més temps sota l'aigua, apujant   |
|           |    l'oxigen fins arribar al limit, llavors s'elimina.  |
|           |--------------------------------------------------------|
|     !     | BOMBONA D'OXIGEN:                                      |
|           |    Serveix per augmentar el nostre limit d'oxigen per  |
|           |    aguantar sota l'aiga, (user->air_max+=5)            |
`--------------------------------------------------------------------'

*NOTA* És important escriure ' ' (espais) en tots els llocs que volguem
       que l'usuari es mogui, ja que si no els hi fiquem, l'interpret,
       ho reconeix com a un fora-de-pantalla i no permetrà el moviment
       cap aquella direccio.



Enllaços:
---------
Logicament, si ens parem a pensar amb tot el que es pot fer de manera plana,
que ja dona bastant de joc i possibilitats, ens trobem amb certes limitacions,
principalment la mida de les pantalles. I la impossibilitat d'enllaçar les
unes amb les altres. D'aqui sorgeix la idea dels enllaços.

A l'hora de crear la pantalla, podem escriure nombres del 0 al 9, aquests
son memoritzats en una taula, esperant a ser dirigides per alguna comanda
definida per comentaris. '#'

Per enllaçar diferentes pantalles cal que ho fem aixi:

#link<nombre>=<nomdefitxer>[:<entrada>]

és a dir, suposem la pantalla següent.

#link1=002.pag
        #####################
        # A               1 #
        #>>>>>>>>>>>>>>>>>>>#

Quan l'usuari passi per sobre de '1' (que l'interpret l'amaga). El programa
cargara el fitxer 002.pag. I si aquest té més d'una entrada d'inici (A..A..)
ens donara a escollir. Pero aixo té facil solucio ja que quan carguem el
mapa podem definir l'entrada que volguem.

#link1=002.pag:2

Es cargara el mapa 002.pag i situara a l'usuari a la segona entrada (la segona
A en el mapa).


Gracies a aquesta manera d'enllaçar, l'interpret també permet crear portes,
punts d'obertura i de tancada. Gracies a la comanda "#door". Que s'utilitza
de la següenta manera:

#door<nombre>=<nombred'obertura>,<nombredetancada>

D'aquesta manera suposem per un moment la següenta pantalla:

#door1=2,3
   ###############################
   #  A                 1     @  #
   ########             ##########
          #             #
          #             ##########
          #(3)         z      (2)#
          ########################

Quan l'usuari pasi per damunt de l'enllaç '3', la porta 1 es tancara. Pero
per exemple si vol aconseguir la vida, haura d'obrir la porta, aixo ho fa
possant-se entre els parentesis, és a dir, sobre l'enllaç 2. Cal comentar,
que inicialment totes les portes resten tancades.



Un altre tipus d'enllaç es el que es realitza mitjançant el comentari
#tele, aquest serveix per teletransportar a l'usuari des d'un punt
origen fins a un final.
exemple:

#tele1=2
                     #
A    1           2   #
######          ######
     #,,,,,,,,,,#
     ############

Quan arribi a 1 apareixera a la posicio 2.

. <- punt i apart :)

Fem un punt i apart, perque dins dels comentaris (variables) del joc, he
implementat dos força interessants: els comentaris de nivell i els
comentaris de joc. M'explico:

Comentaris de nivell:

 Quan es fa una pantalla, podem deixar comentaris pq despres els pugui
 llegir quan s'editi la pantalla, comentaris de l'estil: nom del creador,
 any de creacio, opinions personals, reflexions, acudits o fins i tot
 fragments de la biblia ;)

 Aquests comentaris s'introdueixen a principi de linea utilitzant un ';'
 al igual que amb ensamblador, per exemple:
 ; aixo es un comentari. i nomes serveix per ser llegit :)


Comentaris de joc:

 Aquests tipus de comentaris seran presentats per pantalla quan l'usuari
 entri al joc, centrats a la pantalla. Aquests s'introdueixen de la
 següenta forma:

 #mesg=hola soc un missatge centrat en pantalla.
 #mesg=Aquest nivell no el superes ni de conya!
 #mesg=pop

 Aquests tres missatges apareixeran un per un separats per un "tec" de
 teclat ;)

 L'altre tipus de missatges, poden ser activats quan el jugador passi
 per algun punt en concret de la pantalla, mitjançant els objectes.

 #mesg1=HOLA SOC UN MISSATGE!! (HAS PASSAT PEL LLOC INDICAT)

 A          1  # 
 ###############

 Quan el jugador passi per sobre de l'1, apareixera aquest missatge en
 pantalla.


Objectes:
---------
Gracies als objectes, PAG permet crear elements mobils dins de l'espai.
Aquests elements, es mouen seguint unes trajectories simples, és a dir,
vertical-horitzontal. (En un principi), clar que sempre es poden crear
IA :). En principi, el nombre d'objectes esta limitat a un cert nombre que
depen de com haguem compilat el codi. Pero intentarem en un futur no molt
llunya, que aquest control el faci a través de malloc i per tant puguem
controlar (relativament) infinits objectes.

Principalment ens trobem davant de 2 tipus d'elements mobils:
 - Plataformes.
 - Enemics.
 
El primer bloc és potser el més complert, ja que admet canvis de trajectories
de verticals a horitzontals dreta, esquerra, amunt i avall. Per definir-les
és ben facil:

= o "    Gracies al signe d'"igual" i les "cometes" podem crear plataformes
         mobils. Les generades per signes iguals simbolitzen plataformes de
         moviment horitzontal. I les cometes, plataformes verticals.

Per exemple, una pantalla amb dues plataformes podria ser aquesta:

##############################
                             #
A                            #
#######               ########
    #  =====               #
    ###############      ###
                  #      #
                  #""""""#
                  ########

Explico:
   - la plataforma formada per iguals, es moura horitzontalment cap a la
     dreta fins que topi amb la paret de la dreta, llavors es moura cap a
     l'esquerra.
   - la plataforma formada per apostrofs es moura verticalment cap amunt
     fins que estigui a un espai del sostre, llavors baixara. Aixo es
     perque no permet la chafamenta, es a dir, pots morir punxat pero no
     xafat :).
   - Si una plataforma esta sobre un usuari, aquest inmediatament saltara
     per pujar-s'hi.
     
Canvi de trajectoria:
---------------------
Es posible canviar la trajectoria de les plataformes, de manera que quan 
toqui el sostre giri cap a la dreta. D'aquesta manera:

##########################################
                                         #
  A                                      #
###########/ ====                   \#####
          #                          #
          #                          #
          #                          #
          #\                        /#
          ############################





[4]

-----------------
  COL.LABORACIO
-----------------

PAG es un projecte obert a tothom, qualsevol persona pot col.laborar, en
l'actual estat del projecte, estaria be, que us posesiu amb contacte amb
mi, per començar a organitzar diversos punts importants:

* Interpret amb llibreria grafica. (AA, SVGA, X11, MESA? ;)
* Creacio dels paquets RPM, DEB (bin-i386) o TGZ (cf).
* Correccio d'errors.
  * Calen beta-testers.
  * Calen pegats o consells per solucionar aquests errors.
* Traduccio del manual d'usuari (README.cat) a la resta d'idiomes d'ambit
  mundial. :D
* Calen creadors de nivells del joc. (!!!)
  * Podem crear diversos paquets de nivells.
    * Cada nivell ha de portar un numero com a nom un nombre (001.pag, 002.pag)
    * Seran grabats a /usr/share/games/pag
      És a dir, si es fa un paquet de nivells que es digui "travel"
      Doncs llavors simplement s'escriura:
        /usr/games/pag travel
      i inmediatament ha de cargar el fitxer /usr/share/games/pag/travel/001.pag


Pancake < poptph@hotmail.com >
Membre de CatHack < www.sindominio.net/cathack >


                                                 Salut i lluita companys!
                                                    - ni un pas enrera -