FreeGameDev Wiki watch

Hi, welcome to OpenArena. Thanks for your edit to the [[:Main Page]] page.

'''[[Special:Userlogin|Please sign in and create a user name]]'''. It's an easy way to keep track of your contributions and helps you communicate with the rest of the community.

Please leave a message on [[User talk:Uberfuzzy|my talk page]] if I can help with anything! -- [[User:Uberfuzzy|Uberfuzzy]] ([[User_talk:Uberfuzzy|Talk]]) 23:47, 2 July 2009

<h4>First you should mind the following:</h4>

<ul>
<li>Tux (and other characters) are still composed of spheres. The figures look very nice but drawing them is quite expensive. For better performance the characters should be shaped with a 3D programm, but currently I keep the sphere-orientated method.</li>
<li>Tux is a hierarchical structure of different nodes. It's a good idea to study this structure first. (<a href="../doc/tux01.html">see the overview</a>) It might be helpful to print out the picture.</li>

<li>The shape is defined in the file "char1.lst". The file is written in SP. Remember that all new lines must begin with *; a line without * is appended to the previous line. Each entry has a plausible default value, so you can omit all entries with standard values. At last: the order of the entries is arbitrary since each data field has its own tag.</li>
</ul>

<h4>And now the rules for shaping a friend of Tux:</h4>

<p>There are 3 commands: material, create and prop. The <b>materials</b> must be defined first because some of the following commands apply to the material definitions. With <b>create</b> you create a new node. All new nodes refer to a parent node, so the parent must already exist. The predefined root node is parent of all and called "root". Apart from this essential rule the order of creating nodes is arbitrary. The <b>prop</b> command is only used in special cases (see below).</p>

<p>Normally you define a new node in one line, e.g.:</p>

<pre>
*[cmd] create [node] 13 [par] head
</pre>

<p>In this case, the name of this node is a number (13), and the parent node is called "head". You are free to use numbers as well as letters. This node is unvisible, to create a visible node you have to add the entry [vis]:
</p>
<pre>
*[cmd] create [node] 74 [par] 04 [vis] 8 [scale] 0.95 1.0 0.8 [mat] blackcol
</pre>

<p>The value of [vis] defines the sphere resolution. 10 is best resolution, a lower value draws a coarser sphere. A negative value (default) makes the node unvisible. You see that the sphere is scaled and has a material.
</p>
<p>All nodes can be translated, rotated and scaled. Example:

</p>
<pre>
*[cmd] create [node] 24 [par] left_shoulder [trans] -0.22 0 0 [rot] 1 -90.0
</pre>

<p>The translation entry should be clear, the rotation entry has 2 values. The first value defines the rotation axis (1 = x, 2 = y, 3 = z) in the coordinate system, and the second value defines the rotation angle.
</p>
<p>And now some words about the <b>prop command</b>. In some cases you can't define all node properties in a single line. A line can contain only one rotation, if there are more you have to enter them in additional prop lines. Of course, the affected node has to be created first.
</p>
<pre>
*[cmd] create [node] 34 [par] 28 [trans] -0.23 0 0 [rot] 3 20.0
*[cmd] prop [node] 34 [rot] 1 -90.0
</pre>

<p>Another reason can be the order of the transformation statements. All transformations are stored in a single 4x4 matrix which is built step-by-step. Without specifying a special order the matrix is built in the order translation -> rotation -> scale. Somestimes you need another order, and you can force it with additional prop lines. Example:
</p>
<pre>
*[cmd] create [node] 22 [par] 03 [rot] 2 180
*[cmd] prop [node] 22 [trans] -0.56 0.3 0
*[cmd] prop [node] 22 [rot] 3 45.0
*[cmd] prop [node] 22 [rot] 1 90.0
</pre>

<p>The first rotation is done in the create line, followed by a translation and two further rotations. And of course, you needn't define any property in the create line. Sometimes it might be clearer to use a particular prop line for each property. The following two examples have the same effect:
</p>
<pre>
*[cmd] create [node] 20 [par] 14 [vis] 5 [trans] 0.12 -0.045 0.4 [rot] 2 18.0 [mat] iriscol

*[cmd] create [node] 20 [par] 14 [vis] 5
*[cmd] prop [node] 20 [trans] 0.12 -0.045 0.4
*[cmd] prop [node] 20 [mat] iriscol
*[cmd] prop [node] 20 [rot] 2 18.0
</pre>

<p>That's all about the syntax. Perhaps you want to experiment with the character shape. You can do it by changing the file char1.lst. For a better view on the result open main.cpp and change the entry "cfg.program_mode" in the function InitConfig () from "RACE" to "TUXSHAPE". Then you will see the following screen. The figure on the right is permanently rotated, so you can view it from all directions.
</p>

<p class="centerp">
<img src="images/tuxshape.png" width="600" height="447" border="0" alt="">
<br clear="all"></p>

<h4>So what's a keyframe?</h4>

<p>A keyfame describes a state of motion or animation. Between the different states the motion and animation of the character is interpolated by translating and rotating the entire character or rotating a part of the body. To create a chain of keyframes (also called "keyframe") you have to define at least 2 motion states and the time interval between the two states. Normally a keyframe in Tuxracer consists of 10 - 20 states.</p>

<h4>An Example</h4>

<p>The following keyframe is quite simple</p>

<pre>
*[time] 2.6 [pos] -2 0 0 [yaw] 0 [sh] -60 -60
*[time] 0 [pos] 1.5 0 0 [yaw] 180 [sh] 60 60
</pre>


<p>There are two states, and the time interval from the first to the second state is 2.6 seconds. The position differs from x = -2 to x = 1.5. So the character moves to the right for 3.5 units. The [yaw] defines the viewing direction of the character. With [yaw] 0 the character looks to the viewer, and with [yaw] 180 it shows his rear part. With the keyframe above the character turns smoothly. And the [sh] defines the stance of the arms. The first value is always the left, the second the right arm (or leg, or ankle). The arms are rotated at the schoulder joints (sh).</p>

<p>In this way it goes on, and apparently the last frame doesn't need a time value.
</p>
<h4>List with the possible motions:</h4>

<pre>
[yaw] rotation of the entire body (y-axis)
[pitch] rotation of the entire body (up, down)
[neck] rotation at the neck joint (forward, backward)
[head] rotation of the head (left, right)
[sh] rotation of the arms at the shoulder joints (forward, backward)
[hip] rotation of the legs at the hip joints (forward, backward)
[knee] rotation of the lower legs at the knee joints (forward, backward)
[ankle] rotation of the feed at the ankle joints (forward, backward)
</pre>


<p>Probably you miss some options, for example the arm rotation up and down. At the moment those motions are not implemented, but it's no problem to add them in the code.</p>

<h4>Keyframes in Bunny Hill</h4>

<p>Bunny Hill uses two keyframes: a start keyframe when Tux is moving to the startpoint and the end keyframe after Tux has passed the finishing line. Both must be adapted to the racing phase. That means that the final position in the start keyframe must be (0 0 0) to stop the motion at the startpoint. On the other hand, the end keyframe must begin with the position (0 0 0) to start the motion at the last racing position. Same with the orientation: during the race Tux is sliding on his belly, looking in -z direction. This orientation is described by the following values:
</p>
<pre>
[yaw] 180 [pitch] 110 // pitch = 90&Acirc;° + course angle
</pre>


<p>For the two situations I've written different keyframes, it's really easy! You can choose between 4 start frames (tux_walk, tux_walk2, tux_jump, tux_fast) and 2 finish frames (tux_joice, tux_sad). To enter one of these frames open main.cpp and change the entries in InitConfig ().
</p>
<p>You can test your own keyframes or the modified Bunny Hill keyframes on the course but you may want to see more details. Therefore change the progmode in InitConfig () from RACE to KEYFRAME. Adjust the position with the cursor keys and pagedown/pageup. Press ENTER if you want to repeat the keyframe. The keyframe you want to test must be entered in InitConfig () as "testframe".</p>

<h2>What are terrains?</h2>

<p>Terrains are PNG bitmaps used for covering the natural surface (not the objects and models). Typical terrains are snow, ice, rock, sand, grass etc. The size of the bitmaps should be 256 x 256. It's possible to define terrains with 512 x 512 or 1024 x 1024 pixels but the larger size doesn't have remarkable advantages. On the contrary, the larger bitmaps slow down the race but don't appear much nicer. Important: all terrain bitmaps must be prepared for getting tiled, that means that the edges of adjacent tiles (of same terrain type) must fit together.
</p>
<p>For each terrain a specific color code is defined. The colors appear on the terrain.png and define the terrain covering on the course. The color code can't be changed once it is used on a course. So the colors should be defined cannily. The colors on the terrain map needn't be 100 % exact, the 3 color channels red, green, blue have a tolerance of +/- 15. It's a good idea to use graduated colors with steps of 30, e.g. 60-0-120 or 90-90-210. to keep the compatibility to the classic terrains snow, ice and rock the following color codes are occupied:</p>
<pre>
0-0-0 (ice)
255-255-255 (snow)
128-128-128 (rock)
</pre>


<p>It won't be good to change these codes because many courses already use them.</p>


<p>The properties of all standard terrains are defined in the list "terrains.lst" which is located in the folder <span class="cour">data/terains</span>, together with the terrain bitmaps. A typical entry:
</p>
<pre>
*[name] snow [id] 3 [texture] snow.png [friction] 0.35 [depth] 0.15
[col] 255 255 255 [sound] snow_sound [vol_type] 1 [part] 1 [trackmarks] 1
[shiny] 0 [track_texture] snow_track.png
</pre>


<h4>The properties:</h4>

<p><b>[name]</b> An arbitratry notation to recognize the terrain. The entry is not used internally.
</p>
<p><b>[id]</b> That's the most important entry. The value is internally used to discern the terrain. An ID can't be used twice, so keep care to use an unique number (0 - 63). Default is the snow ID, so if the loading of a terrain fails it will fall back to snow.
</p>
<p><b>[texture]</b> Clear, the filename of the terrain bitmap. If the bitmap doesn't exist, the snow texture is used.

</p>
<p><b>[depth]</b> This value defines how much to dive into the surface. The depth of ice terrain is typically 0. Default = 0.
</p>
<p><b>[friction]</b> The friction coefficent of the terrain. 0 = no friction, 1 = full friction (no motion possible). Default = 0.5.
</p>
<p><b>[col]</b> Color code for the terrain map (3 values in the order red, green blue).
</p>
<p><b>[sound]</b> The sliding sound when Tux touches the surface.
</p>

<p><b>[vol_type]</b> Kind of sliding sound.
</p>
<p><b>[part]</b> A boolean value: 0 = no snow particles when braking or turning, 1 = particles are generated. Default = 0.
</p>
<p><b>[shiny]</b> A boolean value, only for ice: 0 = no reflections, 1 = reflections on the ice. Default = 0.
</p>
<p><b>[trackmarks]</b> A boolean value: 0 = no trackmarks, 1 = with trackmarks. Default = 0.
</p>
<p><b>[track_texture]</b> In the case that [trackmarks] is set to 1 you have to enter a trackmark texture

</p>



<h2>And your own terrains?</h2>

<p>The explanations above relate to the predefined standard terrains. You may want to create a special terrain for your own course which is used only on this particular course. It doesn't make sense to add the terrain to the list of standard terrains since the installation will be too fiddly. So you can write your own terrain list (called "terrains.lst", too) and put it in the course folder, also the terrain bitmaps. To avoid conflicts with the standard IDs you have to use IDs from 64 up to 99. If an ID is not in the range the terrain will be ignored. The structure of the terrain list is the same as of the standard list.

</p>

<p>Courses, especially the contributed courses, are not prepared for keyframes in either case. For example, the destination frame needs a free and flat area behind the finishing line, and that's not always possible. So it's the task of the course creator to decide whether keyframes are used or not - and which frames. The frame names must be registered in the course description (course.lst, in ETR course.tcl):</p>

<pre>
[angle] 25
[length] 1200
...
[start frame] tux_walk.lst
[dest frame] tux_jump.lst
...
</pre>

<p>Perhaps you can enter two destination frames, one for a successful race, another for the failure.</p>

<p>The predefined keyframes for common usage are stored in the <b>character folder</b>. If a course creator wants to use an own keyframe (it's so easy to define it) he can store it in the <b>course folder</b>. The program looks first in the character folder and then in the course folder. If no keyframe ist entered or if the registered frames can't be found the program omits them.</p>

<p>The course structure differs from the structure used in Tuxracer / ETRacer. It's more flexible and contains more information. Here the files in the course directory:</p>

<p><b>elev.png and terrain.png</b>. These bitmaps are wellknown.</p>

<p><b>trees.png and items.lst.</b> The trees.png can be used as yet. But the new courses need a textfile with all items and their positions, scalings and rotations. If this file (called items.lst) exits it will be read and trees.png will be ignored. It items.lst doesn't exist the program will read tree.png and generate a new items.lst. After this additional objects or models can be added manually to the items.lst.</p>

<p><b>course.lst.</b> This textfile contains the course params, it replaces the course.tcl. The entries: </p>

<ul>
<li><b>width - length - play_width - play_length.</b> The wellknown size parameters. I suggest to use a scale factor of 2 - 3. For example, if the width of elev.png is 120 pixels the course width should be in the range 240 - 360. The same with the length. Lower values will effect bumpy motion and with higher values you will lose details.</li>
<li><b>scale.</b> The hight scaling of the course, same as in Tuxracer.</li>
<li><b>angle - speed.</b> In Tuxracer you control the basical speed with the angle of slope, in Bunny Hill there is another param to adjust the speed. It's advisable to set the angle to a value about 20° or lower and fasten the race with the speed param. 1.0 is normal speed.</li>

<li><b>start_keyframe - success_keyframe - failure_keyframe.</b> Here you can enter the keyframe files you want to use. </li>
<li><b>herring - time - scores.</b> That's new. The requirements for a successful course are defined in the course params now. For all kinds of requirements there are 3 values: easy, medium and difficult. Later, in another article, I will describe the rules to determine the values. The third requirement (scores) is a mix of herring and time. The calculation of the scores is normalized, too. Later.</li>
</ul>
<hr noshade size="1">
<h4>Additional resources</h4>

<p>Perhaps the course creator wants to use resources that are not part of the standard resources. In this case he might define his own resources in the course directory. They are only valid for this particular course. The way of defining those resources is the same as of defining the standard resources. For example, if there is a special surface texture the course builder creates a terrains.lst with the same syntax as the list in /data/terrains/. The following extra resources can be defined in the course folder:</p>

<ul>

<li>terrains and related trackmarks,</li>
<li>keyframes for the 3 situations,</li>
<li>object types, objects and object textures,</li>
<li>skyboxes and light adjustments.</li>
</ul>
<hr noshade size="1">

<p>Not to forget: All <b>course-related translations</b> will be in the course directory and not in a common folder. There seem to be two entries which might be translated in different languages: course name and course description. I can't say yet how to enter the translations. In the case there is no translation the program displays the messages in the default language (English).</p>

===[[Code Structure]]===
===Data Structure and Formats===
*[[3D Model Format]]
*[[Course File Format]]
*[[Campaign Format]]
*[[Environment Format]]
*[[Character Format]]
===Collision Detection===
Erin is working on improving collision detection and has posted some helpful documentation here:
http://www.erinacom.de/tux/doc/doc.html
===[[Terrain Rendering]]===
===[[Widget Library]]===
===[[Translation System]]===