q3k
/
extremetuxracer
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updated documentation 

git-svn-id: https://svn.code.sf.net/p/extremetuxracer/code/trunk@548 0420edf4-82e4-42fc-9478-35b55e6d67a3
master
pkeus 2016-01-14 16:53:47 +00:00
parent 1da426d3fe
commit 9e2c214eb9
3 changed files with 61 additions and 195 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
doc/chartool
View File

@ -37,13 +37,4 @@ The character tool of ETR
- There's not a real undo option, that would be too much effort. But you can undo the changes of the current node by typing "u". After selecting another node, the undo will work no longer.
- To save the changes type "s". The tool generates a new character list and stores it back to "test.lst". That can be done anytime.
- To save the changes type "s". The tool generates a new character list and stores it back to "test.lst". That can be done anytime.

127
doc/code
View File

@ -1,104 +1,39 @@
Extreme Tux Racer - Code Documentation
by Reinhard Niehoff, edited by Kristian Picon
---------------------------------------------
Some internal changes:
---------------------------------------------
The Tcl scripting library has been completely replaced with the SP library,
written exclusively for Extreme Tux Racer. Because of this modification, some
modules or methods are now obsolete: the Tcl hash tables, the "list" module etc.
A restrained approach to C++ has been taken. The entire program can be compiled
with g++, but there are only a few C++ classes. Most of these classes are
implemented for the sake of clarity. For example, when you see the function
"Env.DrawFog", you know that this function is declared and defined
in the module env.cpp. The global instance Env of the class CEnvironment is
available throughout the code. The same with some other classes. And of course,
the classes put together data and their functions. This makes the
code clearer.
A substantial change has been made to the phys_sim module (now physics.cpp),
though most of the functions are left unchanged or with little
modification. There is a new class CControl that encapsulates all parameters
of the traditional "TControl" structure, as well as the functions of the old
phys_sim. All of this belongs together, and this class is really sensible
and will simplify the implementation of multiplayer mode. Some functions have
been moved to other modules, for example TuxOrientation to tux.cpp or
FindCourseNormal to course.cpp. All functions should now have a logical location.
----------------------------------------------
Completely or almost completely rewritten modules
----------------------------------------------
The old modules audio.c and audio_data.c have been replaced with audio.cpp.
The old code was, to say the least, too long and convoluted.
The same with game_config, and with many parts of other modules.
A significant number of modules have not been completely rewritten, but
have been altered almost in their practical entirety. For example
winsys.cpp. It is shorter and clearer now, and it contains
the joystick functions (only a few lines). The module joystick.c has
been rendered obsolete.
These are only some examples. Compare the new code with the original code
and you will find that more than 60 % is rewritten. That's less than the
code of the Bunny Hill rewrite, but the intention of the ETR rewrite was
to clean up und clear up the code first, and enhance it
with new functions, later.
One effect of the clearance is shorter code. Three examples:
1) In the old code there are 5 modules responsible for the Tux character:
tux.c, tux_shadow.c, hier.c, hier_cb.c and hier_util.c
That are about 1850 lines in total (okay, 1500 to 1600 lines without comments).
The new code contains all the functions in a single module (tux.cpp)
with a total of 720 lines.
2) The audio modules. In Tuxracer 0.61 there are 2 modules,
audio.c and audio_data.c
with 1630 lines in total. The new code contains only 1 module with 300 lines!
3) The old race_select.c consists of 1300 lines; the reworked, new code
contains 230 lines - and does at least the same, of course.
===============================================================================
Extreme Tux Racer - Code Documentation
===============================================================================
------------------------------------------------------------------
Unchanged modules
------------------------------------------------------------------
Dependencies and Requirements
-------------------------------------------------------------------------------
Some modules are almost unchanged (except the formal style). That doesn't mean
that these modules will never be modified. I think, eventually all the code
must be completely rewritten. But some tasks are not very urgent or too
extensive at the moment. Here the modules which are nearly unchanged:
Extreme Tux Racer is written entirely in C++, and thus requires a C++ compiler
to be compiled. This compiler has to support the subset of C++11 supported by
recent versions of GCC, Clang and MSVC.
view.cpp, quadtree.cpp, hud.cpp, trackmarks.cpp and parts of particles.cpp
Extreme Tux Racer has - though aming to not have more dependencies than
necessary - the following dependencies:
- OpenGL
- SFML (modules: system, graphics, audio and window), version 2.0 or later
------------------------------------------------------------------
Comments
------------------------------------------------------------------
I know, a good code should be well-commented. For me, the best commentation
is a clear and well-ordered structure. It sounds unbelievable but first I
removed all comments in the original code to make it understandable for me.
So excuse the lack of comments in the new code. Perhaps, some day ...
-------------------------------------------------------------------
BTW
-------------------------------------------------------------------
Some people, including the authors of Tuxracer 0.61, prefer the following formal style:
scale_vector( -2. * dot_product( *vel, treeNml ) , treeNml ) ,*vel ) ;
Okay, this isn't very important (there are more important things) for the effectiveness
of the code, but I have problems to putting up with this style. Additionally, the
accumulation of underscores is bothersome:
static vector_t adjust_tux_zvec_for_roll( player_data_t *plyr, vector_t vel, vector_t zvec )
All clear? Oh yes, reading the code of other developers is pleasurable, and
so I leave you with: have fun with my code ;-)
The code is prepared to be compiled on Windows and Unix environments. For
Windows, there exists a solution for Microsoft Visual Studio (see /build); on
Unix autotools are used. With a few changes (mainly to bh.h) it should run also
on other platforms, given that they provide the dependencies listed above.
Coding Style
-------------------------------------------------------------------------------
Extreme Tux Racer uses AStyle to automatically format the source code. For this
purpose, we provide scripts for Windows (runastyle.bat) and Unix (runastyle)
that automatically call AStyle on the entire source code with the flags
specified in astyle.ini.
Final Remarks
-------------------------------------------------------------------------------
Before r548, this file contained a much longer text written by Reinhard
Niehoff. Today, that text is outdated, but it nicely explains what changed
since the days of TuxRacer. So, in case someone is interested in the history of
this project - have a look!

118
doc/guide
View File

@ -1,104 +1,44 @@
Extreme Tux Racer - End User Documentation
by Reinhard Niehoff, edited by Kristian Picon
===============================================================================
Extreme Tux Racer - End User Documentation
===============================================================================
-------------------------------------------
Important keys
-------------------------------------------
-------------------------------------------------------------------------------
1, 2, 3 - different camera modes (standard is 2)
Tux is steered by the following keys:
Arrows - control direction and speed
Space - Charge for jumping, jump when released
The appearance is modified by following keys:
1, 2, 3 - select camera mode (default is 2)
f - hide or show fps display as part of the hud (heads-up display)
s - screenshot (in folder "screenshots")
h - hide or show hud
u - toggle snowflakes on menu screens
h - toggle on/off hud
u - toggle n/off snowflakes (menu screens only)
F5 - toggle on/off skybox
F6 - toggle on/off fog
F7 - toggle on/off terrain
F8 - toggle on/off trees and objects
There are some special functions which might be relevant for newcomers
who are interested in the compoments of the scenery. You can toggle
the following elements:
F5 - skybox
F6 - fog
F7 - terrain
F8 - trees and objects
For generating the item list by parsing the trees.png file the
following keys might be helpful:
t - sets priority to trees.png and generates an items.lst
c - value of size of trees (1 ... 5)
v - value for size variation (1 ... 5)
-------------------------------------------
The configuration screen
-------------------------------------------
-------------------------------------------------------------------------------
The most important adjustments can be done at runtime at the
config screen. Most options should be self-explanatory.
"Auto" for resolution means that the program uses the same values
as set in the basic computer configuration. That's not convenient
in windowed mode since it ignores the menu/task bar on the screen.
The most important adjustments can be done at runtime at the config screen.
Most options should be self-explanatory. "Auto" for resolution means that the
program uses the same values as set in the basic computer configuration. That's
not convenient in windowed mode since it ignores the menu/task bar on the
screen.
There are 3 levels of detail:
There are 4 levels of detail:
1 - for very slow computers (no trackmarks, particles etc.)
2 - most details are shown but on an lower level
3 - best appearance, today's computers should have no problems with this
3 - good appearance but using lower resolution textures (default)
4 - best appearance, today's computers should have no problems with this
The adjustments are entered and stored in the file "options".
Editing this file is possible, but not necessary.
# 0 = framed window | 1 = fullscreen
[fullscreen] 1
# resolution type: 0 = auto | 1 = 800 x 600 | 2 = 1024 * 768
[res_type] 0
# level of details 1 ... 3
[detail_level] 3
# maximal values are 120
[sound_volume] 60
[music_volume] 30
-------------------------------------
The options file
-------------------------------------
The following adjustments must be done by editing the options file,
they don't appear on the config screen. The file is not commented
yet, that will be done in a future version.
# Index to a language list
[language] 0
# the distances where the course clipping begins
[forward_clip_distance] 75
[backward_clip_distance] 20
# field of view, similar to the focal length at a camera lens
[fov] 60
# color depth, 0 = auto, 1 = 16, 2 = 32
[bpp_mode] 1
# some performance parameters
[tree_detail_distance] 20
[tux_sphere_divisions] 10
[tux_shadow_sphere_div] 3
# This parameter should be obsolete soon. It's the distance where
# the trees are not drawn crosswise but as simple plane textures.
[course_detail_level] 75
# You can choose between 2 font styles: 0 Helvetica, 1 Papercut
# If the value is 2, the huds are drawn with Papercut, too
[use_papercut_font] 1
# Cursor style: 0 normal alrrow cursor, 1 icicle
[ice_cursor] 1
# Normally the sky is drawn with 6 textures (a cube). In the Tuxracer scene
# are only 3 textures visible (left, front, right). So it's faster to draw
# only the visible textures. In addition, it spares resources.
# If set to 1, all 6 textures will be drawn (they have to exist!).
[full_skybox] 0
The adjustments are entered and stored in the file "options". Editing this
file is possible, but usually not necessary.