View source for 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

=== [jumppoint] section ===

=== [jumpgate] section ===


=== [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''.

[[File:Morgan-Keenan_spectral_classification.jpg]]

Project::OSiRiON roughly follows the Morgan-Keenan spectral classification. Consult the [http://en.wikipedia.org/wiki/Stellar_classification wikipedia article on stellar classification] and [http://en.wikipedia.org/wiki/File:Morgan-Keenan_spectral_classification.png 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.

==== [ship] subsection ====

==== [cargo] subsection ====

==== [weapon] subsection ====

=== [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