[Underware-devel] Global architecture

[Loic Dachary]

        Hi,

        On monday we spent the day talking about the global architecture
of the code. It is described in the notes below. Although I admit that it
is hard to interpret as such, it is best to archive it on this list 
anyway. Comments are welcome, specially from people who attended the meeting
and discover a misunderstanding by reading the following ;-)

        I'll structure the current code to match this view by the end
of the week so that we can refine it based on working code.

        We took an hour or so to discuss the limits of cal3d and 3ds
that we currently use to store data. The question really is to figure
out when and how we jump into the unavoidable work of writing a 3d
file format that better matches our needs and all the export/import
tools associated to it.

        Cheers,

----------------------------------------------------------------------
* Files

  pong.game.gpy : description of a game (as simple as possible for a start)
     number of game mode : (numeric)
        repat 
          game mode : (versus/versus player)
          number of player : (possible regular expression)
          network : ( yes, no, both, i.e. optional)
     game options : (pong.settings.gpy)
     score : 
     player name :
     number of sequences (that are really scripts) : 2
         repeat
          sequences description : (intro.sequence.gpy, lobby.sequence.gpy, 
versus.sequence.gpy)

  pong.settings.gpy :
      keyboard : (keyboard preferences)
      avatar : (user choice among available avatars)
      networkspeed : (modem, ADSL...)
      sound : (volume...)

  *.sequence.gpy : [ A sequence starts with a script. It loads a player. It is a
     set of instructions that also contains a set of external resources
     (URL). The underlying code does not contain any external resources.]

     external resources : (set of external resources)
     URL to python script that uses the external resources

  intro.sequence.gpy: 
     video : intro.avi
     script : intro.py 
     loop : forever

  pong.sequence.gpy :

  .wav,.ogg : sounds
  .cal : animated objects
  .py : python scripts
  .3ds : geometry
  .3d : binary file starting with an XML file describing the structure of
        the following binary data.

* Binary file format

  XML length in bytes
  XML chunck
  Binary chunk

  XML schema

  The XML chunk refers to the binary chunk with offsets relative to the 
beginning of
  the file.

  Data compression.

  Versioning: when the XML schema changes the version is incremented.
              an XSL file is produced to migrate from v N to v N+1 a
              program uses the XSL file to migrate the XML part and,
              if necessary, to transform the binary part.

  3D format:

     

* Screens

  Screen 1:

         Versus  mode

         Quit / Enter

* Naming and paths

  Extensions are all optional and chosen for user convenience. There
  are two types of data files : xml and python. The program must
  figure out the XML files type from the type stored in the XML file
  itself and must not rely on the extension.

  *.game.gpy : XML global gameplay description
  *.sequence.gpy : XML describing a gameplay script context
  *.settings.gpy : XML Game settings
  *.py : python scripts
  *.png / *.tga / *.dds : textured images (see nel/src/misc/bitmap.cpp)
  *.ttf : fonts
  *.wav,*.ogg : sound

  A tree organisation of the data is not imposed. It may be a tree or
  a flat directory.

* Classes and XML Schema

  For sequences:

  XML Schema
  .script.context
        intro.script.context
                pongintro.script.context
        game.script.context
                verssus.script.context
                        ponggame.script.context

  A class Context encapsulate the access to the XML tree using a simple API:
  context.get[string] -> return the resource matching the XPATH "string".

  Classes
  [Scripts are given the internal XML tree when created to influence their 
execution]
  .script
        intro.script
                pongintro.script
        game.script.context
                verssus.script
                        ponggame.script

  For Settings

  Classes
  .settings
        arcade.settings
                pong.settings

* OpenSceneGraph

  - It cannot load skinned objects. That may explain why cal3d
    implementation that does not rely.

  Object representation:

  Load vertices
  Load faces
  
  Skinned object:

  Each vertex is associated to a matrix with a weight.

  - Blend shape implementation, how ?

----------------------------------------------------------------------

* Highest level code to run the pong

  pong.versus.sequence.gpy

  XML context:
      <scene>pong.scene.gpy</scene>

  Script:

load

  level->import_scene(context->scene)

play
  for i in 1 2 
    player[i] = gameplay->player(i)
    paddle[i] = gampeplay->paddle(i)
    plus = gettimeaction(settings->UP)
    minus = gettimeaction(settings->DOWN)
    paddle->setlocation((plus - minus) * paddlespeed)
    ball = gameplay->ball(speed, initial_direction)


    ball->position(center)
    ball->speed(random)
    wait(ball->location < 0 || ball->location > 1)
    if(ball_exited_because(player[0])
        player[0]->score++
    if(ball_exited_because(player[1])
        player[1]->score++
  

  if(player[0]->score > 15) "player0 wins"
  else "player1 wins"

  exit

update(delta)
  ball->location->add(speed * delta)
  if(ball.x is in bounds)
    if(ball.y < scene->getpaddle(0)->getlocation())
         ball.bounce()
         cgimedia->sound("bounce")->setlocation(ball)