The Osirion Project - Creating models

When the client has started it will show you the main menu. Click the - Start button to start a local game, the Internet - button will take you to the test server. -

+ Start button to start a game, or click the Internet + button to connect to the test server. +

The Options button will open the options menu where you can - customize your settings. -

When the game has started it will show you the game menu. Click the Join button to join the game, or click the Disconnect button to leave the game and return to the main menu. -

Once you have joined, you will find yourself on Alexandria, a small trading outpost on the edge of the civilized world. You begin the game as the proud owner of a small trading vessel and a modest amount of credits. - Click the Launch button to launch into space. +

Press the V key to switch to the next view. +

Press v to switch to the next view.

Press shift + V to switch to the previous view. +

Press shift + v to switch to the previous view.

If the camera is in tracking view or cockpit view, you can drag the mouse to - turn your space ship. If mouse control is disabled, click and hold the left mouse + turn your spaceship. If mouse control is disabled, click and hold the left mouse button while you drag.

Press spacebar to toggle mouse control on or off. diff --git a/doc/icons/launch.png b/doc/icons/launch.png new file mode 100644 index 0000000..e530e6b Binary files /dev/null and b/doc/icons/launch.png differ diff --git a/doc/main.css b/doc/main.css index 2791bff..80704ee 100644 --- a/doc/main.css +++ b/doc/main.css @@ -1,3 +1,9 @@ +/* + Project::OSiRiON + + documentation stylesheet +*/ + a { color: #dd0000; text-decoration: none; @@ -58,6 +64,8 @@ img { padding: 4px; border-top: 1px solid #606060; border-bottom: 1px solid #606060; + border-left: 1px solid #606060; + border-right: 1px solid #606060; } .banner, .header, .footer { @@ -92,13 +100,14 @@ img { .subtitle { background: #e7e7e7; margin-left: 48px; - margin-right: 24px; + margin-right: 72px; margin-top: 8px; margin-bottom: 8px; font-size: 12pt; border-top: 1px solid #606060; border-bottom: 1px solid #606060; border-left: 1px solid #606060; + border-right: 1px solid #606060; padding: 4px; padding-left: 8px; } @@ -192,7 +201,7 @@ img { margin-right: 48px; margin-top: 8px; margin-bottom: 8px; - padding-left: 16px; + padding: 8px; font-family: "Courier New", "Courier", "fixed"; font-size: 12pt; vertical-align: text-top; @@ -226,3 +235,13 @@ img { padding-right: 32px; vertical-align: top; } + +td.wide { + padding-right: 16px; + text-align: right; + width: 156px; +} + +td.narrow { + width: 64px; +} \ No newline at end of file diff --git a/doc/models.html b/doc/models.html index bd0565a..68351bf 100644 --- a/doc/models.html +++ b/doc/models.html @@ -2,16 +2,21 @@ - - The Osirion Project - Creating models + + Project::OSiRiON - Creating models + -

- The Osirion Project - Creating models -

The engine supports two kind of models: The first one are - Quake 3 style .map files with custom osirion entities. The second + Quake 3 style .map files with custom entities. The second one are .ase models. Textures are supported, but no advanced features like normal mapping.

@@ -19,8 +24,8 @@ The .map format allows for a quick and easy way to create usable 3D models, while the .ase format allows importing more complex models made with modelling packages. The .map format is also used - as a container format to place tags on models, like lights, - smoke trails and weapon locations. + as a container format to place model tags like lights, + particle effects and weapon locations.

.ase models can be loaded as sub-models into a .map file, @@ -29,16 +34,20 @@

The rest of the document describes how to create models using - GtkRadiant and contains mostly information specific to creating - models for The Osirion Project. Even if you can handle GtkRadiant, + Radiant and contains mostly information specific to creating + models for Project::OSiRiON. Even if you can handle Radiant, it is still worth a read.

- Creating models with GtkRadiant -

- All the models for the game were created with GtkRadiant 1.5, - in theory any editor capable of exporting Quake 2 .map files could - be used. Support for files for GtkRadiant 1.5 are included in the - data distribution. Refer to the file INSTALL on where to find them - and how to install them. No map compiler is necessary, the engine - reads the .map files directly. -

- If you are using a linux-based operating system, you can also use - the GtkRadiant distribution from http://ingar.satgnu.net/gtkradiant. + +

+ All the models for the game were created with GtkRadiant 1.5 and NetRadiant, + in theory any editor capable of exporting Quake 3 .map files could + be used. Support for files which can be used with NetRadiant or GtkRadiant 1.5 + are included in the data distribution. Refer to the file INSTALL on where + to find them and how to install them. No map compiler is necessary, + the engine reads the .map files directly. +

+ You can also use the NetRadiant distribution from + http://ingar.satgnu.net/gtkradiant. Note that it does not include the Osirion support files by default. -

This document will not explain how to use the editor. Consult google for numerous tutorials on this subject. All basic brush editing techniques for any Quake-engine based game can be used. -

The main difference with other games is that you are not creating - a map for a 3d-shoot'em'up but, obviously, an object that has to be + a map for a 3d-shoot'em'up, but obviously, an object that has to be loaded into a space game. -

Because there is no map compile involved, and the engine is fundamentally different, some points should be take under consideration. +

Brushes and sizes -

- The engine supports brushes only. Patches will be ignored. A large number + The engine only supports brushes only, patches will be ignored. A large number of complex brushes is supported, but I advise not to go below grid size 1. As with any engine it is still possible to create brushwork that gets - messed up. -

+ messed up due to rounding errors. +

When the model is loaded, the bounding box is calculated. The model will be automaticly centered around the center of the geometry. All visible faces will be converted to triangles. At the moment the practical triangle count limit for a model is between 20,000 and 30,000 brushes. The engine is capable of handling a lot more, but think about the fact that a large station might be placed in a system filled with player ships and other objects. -

The limits of map coordinates are placed on +/-16384 map units. Placing brushes outside these bounds will have unpredictable results. The map will be scaled down to make 1024 units in radiant correspond to 1 game unit. One game unit corresponds to 100m in-game. 16 units in radiant will therefor correspond to 1.5625 meters in-game. -

The front of a model points along the positive X-axis, the positive - Z-axis is up, the positive Y-axis is left. In GtkRadiant, the nose of - the spacesip or the front of a spacestation should point to the right. + Z-axis is up, the positive Y-axis is left. In Radiant, the nose of + a spacesip or the front of a spacestation should point to the right. +

+ +

Caulk -

Any brush face that has the common/caulk texture will be ignored on load. + Note that common/caulk is actually a special material with the ignore flag set. +

+ Like in Quake 3 maps, all invisible brushes faces should have the this material.

+

Any brush face that has the common/clip texture will be ignored on load. + Note that common/clip is actually a special material with the ignore flag set. Clip is reserved for future use.

+

As with other engines, Osirion supports the use of detail brushes, but with a twist: detail brushes will only be rendered if the model is within detail range, close enough to the camera. When it is further away, only structural brushes will be rendered. The actual detail range depends on the size of the model. -

This means that any object that could only been seen from close by should be made from detail brushes. -

This has one improtant implication: if you show the structural brushes only (with the CTRL+D filter in Gtkradiant) there should be no obvious gaps of caulk that were previously hidden behind detail brushes. -

+ +

Textures and Materials -

- The engine can use tga, jpg and tng images as textures and uses a simple + The engine can use TGA, JPEG and PNG images as textures and uses a simple script based materials system similar to Quake 3 Arena shader files. Materials make it possible use special textures like player and engine color, or to apply certain effects to a texture. @@ -152,7 +186,7 @@

The default shaderlist.txt looks like this:

+ common
 colors
 glass
@@ -186,20 +220,22 @@ glass
 	by the engine: as explained above, the common/caulk material can be used
 	on hidden faces. The common/clip	material is reserved for future use
 	brush faces using this texture will be ignored as well.
-
-
+

 	For .ase models, the material name inside the .ase file is interpreted as an osirion material.
 	If you'd use a material called  common/entity, those model faces will rendered using
 	the object's primary in-game color, regardless of the actual material settings in the .ase file.
 
-	
-
+

TODO: write a section on shader files.

+ // material name
 textures/common/clip
 {
@@ -211,7 +247,7 @@ textures/common/clip
     ignore
 }
 
-+ // material name
 textures/common/entity_dark_bright
 {
@@ -225,58 +261,64 @@ textures/common/entity_dark_bright
     bright
 }
 
-+ // material name
-textures/ship/stripes
+textures/ship/plating_entity
 {
     // use entity color
     entity
     // use a texture, texture name and material name don't have to be the same
-    texture textures/ship/stripes
+    texture textures/ship/plating
 }
 
+

+ +

Lights -

Unlike quake, light entities are not used to add lighting information to the level but to add point lights to a model. Adding a light will render a light flare texture in the corresponding location. -

The flare value indicates what texture will be used to draw the light. The flare value is translated to a texture name, bitmaps/fx/flare??. The default flare texture is flare00. -

The light value is used to determine the size of the flare. The engine default is 100, resulting in rather large flares. -

The default _color is white, but the color can be set through radiant's color menu (K key). If the entity option (spawnflag 2) is set, the color value will be ignored and the light will be rendered with the color of the entity it is attached to. -

The strobe option (spawnflag 1) will create a blinking light. A number of options can be set to manipulate the flashing behaviour. By default a strobe light will be half a second on, half a second off. -

The frequency value changes the number of flashes per second. -

The offset value changes the moment the light will be on. Offset is measured in seconds. -

The time value sets the fraction of time the light will be on. The default is 0.5. -

Lights will only be rendered if the model is within detail range. -

I also came across this usefull information: http://en.wikipedia.org/wiki/Starboard
- In short, the green light should be on the right side, the red light on the left side. +

+ +

Flares -

The default light entity creates omnidirectional lights. To create a directional flare, use the fx_flare entity. Values for a @@ -297,10 +339,13 @@ textures/ship/stripes

Flares will only be rendered if the entity is within detail range.

+ +

Particles -

Add a fx_particles entity to attach a particle system to the model. They can be used to add effects like trails and smoke. A particle system @@ -320,9 +365,13 @@ textures/ship/stripes

Particles will only be rendered if the entity is within detail range.

+

Brushes can be grouped together into funcion groups. These groups can be used to create moving parts in a model. @@ -338,15 +387,23 @@ textures/ship/stripes is automaticly calculated as the geometrical center of the group. The rotation axis can be set with the direction, pitch and roll keys. angle is an alias for direction.

+

misc_model can be used to add a submodel.

+

location_cockpit, location_dock, location_turret and location_cannon are reserved but have not yet been implemented.

@@ -360,9 +417,8 @@ textures/ship/stripes

location_turret will create an attachment point for turrets. Turrets point upwards or downwards.

- back -

- The Osirion Project - Editing the world -

One of the goals of the project is to create a game world that is easy to adapt and extend. At the moment of writing, the game reads the @@ -16,33 +21,37 @@ from ini/ships.ini. These ini-files are plain text files that can be edited with any text editor.

- The world description files are server-side. This means that editing your local - copies will not affect the world when you connect to a remote server. Someone - connecting to your server will also receive your modified world. + The world description files are server-side. If you run your own server + you can modify the world to your and clients will automaticly join your + modified world.

I recommend you do not edit the original game data, copy the files you want - to edit toyour personal osirion directory. The files found in this directory will + to edit to your personal osirion directory. The files found in this directory will get precedence over the original game data. Your modified files will be used and the original files can still be updated when a new version is available.

- On Linx and other Unix-systems your personal osirion is a hidden directory called + On Linux and other Unix-systems your personal osirion is a hidden directory called .osirion in your home directory. On windows, your personal osirion directory is My Documents\My Games\Osirion.

File structure -

World description files use the windows ini-file syntax. These files contain one or more sections. Every section starts with a section name enclosed in square brackets and contains a list of value=key pairs to describe the properties for the current section. Lines starting with a semicolon are considered comments and are ignored.

- For example, a section planet describing a planet called Seymour: + For example, a section describing a planet called Seymour:

+ [planet]
 label=seymour
 name=planet Seymour
@@ -51,27 +60,38 @@ color=1 .9 .5
 texture=planets/seymour
 radius=68
 
+

+ + +

Textures -

The engine supports textures in the TGA, PNG and JPG file formats, where required. The filename extension should be lowercase and in 24bit RGB or 32bit RGBA format.

- World -

The file world.ini contains a list of zone labels. A zone is a seperate compartment in the gameworld, like a solar system or a remote sector in space. It contains a single world section containting multiple zone keys.

- [world] -

@@ -82,16 +102,21 @@ radius=68

Note: a label can only contain letters, numbers and underscores. Any other character is deleted. This applies to any label in any .ini-file.

+ ; a world.ini with two zones
 [world]
 zone=ghant
 zone=brogha
 
+
+
 
-
+
+
 	Zones
-
+
+
+
 
 	Each zone has its own zone description file. The actual name of the file depends on the zone label. 
 	If your world.ini contains the line zone=ghant, the content of the zone with 
@@ -100,9 +125,13 @@ zone=brogha
 	The .ini-file containts a list of objects populating that zone, and the basic properties of those
 	objects. In the context of the engine, such an object is called an entity.
 
-
-    [zone]
-
+
+
+
+    [zone] section
+
+
+
 
 	Every zone description file has a zone section describing a few of its basic properties:
 
@@ -115,16 +144,16 @@ zone=brogha

- + - +

zone =
sky =	[string]	name of the skybox in textures/sky directory	name of the skybox in the textures/sky directory
default =	[bool]	mark this zone as the default zone for the game, only one zone can have this key set to yes, can be omitted elsewhere	mark this zone as the default zone for the game, only one zone should have this key set to yes, can be omitted elsewhere

+ ; ghant.ini
 ; zone description file for the Ghant system
 [zone]
@@ -146,14 +175,17 @@ default=yes
 	The _down image has to be rotated, 90 degrees counter-clockwise
 
 
+

- [entity] -

You can add several entity sections to define the objects occupying your zones. Entities come in two flavours: basic geometrical shapes and entities with models. Both have a similar definition and set of properties. A simple entity is considered decoration by the engine and won't change direction or location.

- Every in-game entity should have a label key. If the entity in question is going to be used as a base, or any object the could be referenced in possible scripting, it should have a unique label. The label should be lowercase and not contain spaces. A player-friendly name can be provided through the name key. + Every in-game entity should have a label key. If the entity in question is going to be used as a base, or any object the could be referenced in possible scripting, it should have a unique label. The label should be lowercase and not contain spaces. A player-friendly name can be provided through the name key.

@@ -166,6 +198,11 @@ default=yes + + + + +

[string]	the in-game name of the entity
info =	[string]	the in-game description, multiple info key can be used to add long descriptions

@@ -273,7 +310,7 @@ default=yes An example of an entity with a basic shape:

+ [entity]
 label=origin
 name=Galactic origin
@@ -282,12 +319,15 @@ radius=1
 location=0 0 0
 ; yellow
 color=1 1 0
+; description
+info=The Galactic origin is a turbulent area filled with hot plasma, ion storms and magnetic radiation.
+info=Travelers entering this region do so on their own risk.
 
 
 
 	An example of an entity with a model:
 
-+ [entity]
 label=ikarus
 name=Ikarus satellite
@@ -298,23 +338,20 @@ location=64 0 0
 direction=120
 pitch=15
 
+

[station] -

- A station section defines an entity that can be visited by a player. This section + A station section defines an entity that can be visited by a player. This section can contain the same keys as the entity section, but the entity will be marked as dockable and the player will be able to target it for docking.

- The engine will load the stations menu descriptions from the file zones/zonelabel/entitylabel.ini. - For example, if your zone has the label ghant and your entity has the label alexandria then - the engine will try to read zones/ghant/alexandria.ini. Read the section on entity menus for more - information. -

+ [station]
 label=alexandria
 name=Alexandria outpost
@@ -324,24 +361,28 @@ location=-192 -704 32
 color=222 192 145
 direction=45
 
+

[navpoint] -

Space is huge and barren wasteland. Navigation points are an easy way to provide players with landmarks. The default navigation point is a diamond-shaped entity.

+ [navpoint]
 label=navpoint_east
 name=Navigation point East
 location=716 -1008 20
 
+

[jumppoint] -

Jumppoints are the key to interstellar travel. A ship equiped with a hyperspace jump drive can use it to travel to other starsystems. A jumppoint looks like a @@ -352,15 +393,15 @@ location=716 -1008 20 target = [string]:[string] - zone:entity
- the label of a the target zone and the target jumppoint. + zone:entity the label of the target zone and jumppoint. - -

+

Jumpgates are build on top of jumppoints and can be docked by smaller ships to travel to other starsystems. Just like the jumppoint section, the jumpgate @@ -369,7 +410,7 @@ location=716 -1008 20 Jumppoints and jumpgates can target each other and ships equiped with a hyperspace jumpdrive can still use the jumpgate to jump as usual.

+ [jumpgate]
 label=jumpgate_brogha
 name=Jumpgate Ghant -> Brogha
@@ -379,12 +420,14 @@ location=716 -1024 24
 direction=90
 color=222 192 145
 
+

[planet] -

- A planet is spherical entity with a texture. and a default radius of 64. The planet globe will + A planet is spherical entity with a texture and a default radius of 64. The planet globe will be rendered with lighting enabled. A planet can be marked as dockable. In this case it can be visited by a player and menu descriptions will be loaded.

@@ -406,7 +449,7 @@ color=222 192 145 -

+ ; The iceworld, a very dark and cold place
 [planet]
 label=iceworld
@@ -414,21 +457,23 @@ name=The World of Ice
 texture=planets/iceworld
 rotationspeed=1
 ; a grey-blue colour
-color =0.5 0.5 0.8
+color=0.5 0.5 0.8
 
+

[star] -

A star is a spherical entity with a default radius of 96. The star globe - will be rendered fullbright and serve as the main source of light for the current system. + will be rendered fullbright and serves as the main source of light for a zone. At the moment only one system light source is supported. If you define multiple stars, - the last one will serve as light source. Stars can have a texture. + the last one will serve as light source. Stars can have a texture like planets.

-; a yellow star
++; a white dwarf
 [star]
 label=whitedwarf
 name=White Dwarf
@@ -440,15 +485,18 @@ radius=96
 	Consult the wikipedia article on stellar classification
 	and this image.
 
+

[ship] -

Some planets and stations have ship dealers where players can buy a new ship. [station] and [planet] - sections can be followed by one or more [ship] sections to add ship models to the ship dealers inventory. + sections can be followed by one or more [ship] sections to add ship models that can be purchased + on that location.

+ ; station definition
 [station]
 label=alexendria
@@ -469,9 +517,12 @@ label=alexendria
 	but it improves readability. The label key is mandatory and referes to
 	a ship type as defined in ships.ini.
 
-
+

Cargo trade is defined similar to ship dealers. [station] and [planet] sections can be followed by one or more [cargo] section to add specific items to the trader's inventory. The label @@ -492,7 +543,7 @@ label=alexendria -

+ ; station definition
 [station]
 label=alexendria
@@ -510,26 +561,38 @@ label=alexendria
 	price=200
 	amount=0
 
+

- The Osirion Project - Creating models -

+

- Creating models with GtkRadiant -

+
Brushes and sizes -

+ +
Caulk -

+

+

+ +
Textures and Materials -

+

+ +
Lights -

+ +
Flares -

+ +
Particles -

+

+

+

- back -

- The Osirion Project - Editing the world -

+
File structure -

+ + +
Textures -

- World -

- [world] -

+ +
Zones -

- [zone] -

- [entity] -

+
[station] -

+
[navpoint] -

+
[jumppoint] -

+

+
[planet] -

+
[star] -

+
[ship] -

+

- Ships -

- Cargo -

- back -

- The Osirion Project - Creating models -

+

- Creating models with GtkRadiant -

+ Brushes and sizes -

+ + Caulk -

+

+

+ + Textures and Materials -

+

+ + Lights -

+ + Flares -

+ + Particles -

+

+

+

- back -

- The Osirion Project - Editing the world -

+ File structure -

+ + + Textures -

- World -

- [world] -

+ + Zones -

- [zone] -

- [entity] -

+ [station] -

+ [navpoint] -

+ [jumppoint] -

+

+ [planet] -

+ [star] -

+ [ship] -

+

- Ships -

- Cargo -

- back -

+
Brushes and sizes -

+ +
Caulk -

+ +
Textures and Materials -

+ +
Lights -

+ +
Flares -

+ +
Particles -

+
File structure -

+ + +
Textures -

+ +
Zones -

+
[station] -

+
[navpoint] -

+
[jumppoint] -

+
[planet] -

+
[star] -

+
[ship] -