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 world description from ini/world.ini and a list of buyable ships 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. If you run your own server you can modify the world to your liking and clients will automatically join your modified world.

I recommend you do not edit the original game data, copy the files you want 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 Linux and other Unix-systems your personal osirion is a hidden directory in your home directory called .osirion. 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 describing a planet called Seymour:

 ; Planet Seymour
 [planet]
 label=seymour
 name=planet Seymour
 location=-128 1024 -32
 color=1 .9 .5
 texture=planets/seymour
 radius=68

You can edit the ini files with a text editor of your liking.

World definitions

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

The player can only travel between zones by using a jumpgate or ship equiped with a hyperspace jump drive.

[world] section

key	value	usage
zone=	[string]	label of the zone to be added to the game world

Example:

 ; a world.ini with two zones
 [world]
 zone=ghant
 zone=brogha

Zone definitions

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 the label ghant would be described in the file zones/ghant.ini.

The ini-file contains 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] section

The zone section defines a number of attributes for the current zone. Note that if a zone faction is set, the zone color will default to the faction's color. You can override the faction color by placing the color key after the faction key.

key	value	usage
name=	[string]	the in-game name of the zone
sky=	[string]	name of the skybox in the textures/sky directory
color=	[r g b]	color used to display this zone on the map
faction=	[label]	faction this zone belongs to
ambient=	[r g b]	ambient light color for this zone
location=	[x y z]	galactic location of the zone
info=	[string]	The in-game description, multiple info key can be used to add long descriptions.

Example:

 ; Zone identification for the Ghant system
 [zone]
 name=Ghant system
 sky=sky02
 ambient=0.1 0.1 0.1
 location=100 -50 0

[entity] section

The [entity] sections adds a generic entity to the zone

key	value	usage
label=	[string]	The game label for this entity.
name=	[string]	The in-game name for this entity.
info=	[string]	The in-game description, multiple info key can be used to add long descriptions.
shape=	[shape]	Set the shape key to define a basic geometrical shape:
	axis	A 3D-axis with X, Y and Z lines.
	cube	A cube.
	diamond	A rotating octahedron with an axis.
	sphere	A polyhedron approximation of a sphere.
model=	[string]	Filename of the model for the entity, without extension. Setting the model key overrides the shape key.
radius=	[float]	Radius of the entity, in game units: 1 game unit translates to 100m in-game. An entity with a radius of 0.5 would fit into a sphere with a diameter of 100m. The radius is automaticly calculated for entities with a model.
location=	[x y z]	Location of the entity within the zone.
yaw=	[float]	Yaw angle of the entity, in degrees.
pitch=	[float]	Pitch angle of the entity, in degrees.
roll=	[float]	Roll angle of the entity, in degrees.
color=	[r g b]	Primary entity color.
colorsecond=	[r g b]	Secondary entity color.
showonmap=	[bool]	If true, this entity appears on the map.
nonsolid=	[bool]	If true, this entity will be ignored by collision detection.

An example of an entity with a basic shape:

 [entity]
 label=origin
 name=Galactic origin
 shape=axis
 radius=1
 location=0 0 0
 ; yellow
 color=1 1 0
 ; description
 info=The Galactic origin is a turbulent area filled with hot plasma, 
 info=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
 model=maps/satellites/ikarus
 ; blue
 color=100 100 230
 location=64 0 0
 yaw=-120
 pitch=15

All other entity sections, like [station] and [star] derive from [entity], this means that all entity keys can be applied to the other sections as well.

[navpoint] section

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.

Example:

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

[star] section

A star is a spherical entity with a default radius of 96. The star globe will be rendered fullbright and serves as the main source of light for a zone.

Stars can have a texture like planets. Aditionally, the corona key can be used to indicate what corona texture to use to render the star's corona. Corona textures can be found in textures/corona.

Project::OSiRiON roughly follows the Morgan-Keenan spectral classification. Consult the wikipedia article on stellar classification and the classification image.

Example:

 ; a class G star
 [star]
 label=star
 name=class G star
 color=1.0 0.9 0.5
 radius=96
 corona=default

[planet] section

A planet is spherical entity with a texture and a default radius of 64 and will be rendered with lighting enabled. A planet can be marked as dockable: in this case it can be visited by a player and trading definitions can be added.

key	value	usage
texture=	[string]	Name of the texture used to render the planet.
rotationspeed=	[float]	Rotation speed in degrees per second
dock=	[bool]	Set to tro to create a planet that can be visisted.

Example:

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

[station] 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.

Stations can sell cargo and ships. Trading definitions are set in cargo and ship sections following the station section.

key	value	usage
faction=	[string]	Faction this station belongs to, as defined in factions.ini.

Example:

 [station]
 label=alexandria
 name=Alexandria outpost
 model=maps/stations/alexandria
 location=-192 -704 32
 ; brown
 color=222 192 145
 yaw=45

Trade definitions

Dockable planets and stations are the trading centers of the universe. To define tradeable goods and ships the planet and station secionts can be followed by one ore more cargo, ship or weapon subsections. Each entry will add an item to the planet's or station's inventory.

[patrol] section

Defines NPC patrols.

[npc] subsection

The npc subsection will define with type of NPCs the patrol will consist of.

[waypoint] subsection

Waypoints define a patrol's travel path.

Templates

 templates.ini

Factions

 factions.ini

Ship definitions

 ships.ini

Cargo definitions

 cargo.ini

Weapon definitions

 weapons.ini