path: root/README

The Osirion Project - README

	This is the Osirion project. I wrote it to get a better grasp on
	game design with OpenGL and to get some C++ practice.
	Maybe someday it will be a real game.

	Read INSTALL for instructions on building, installing and updating.

Client

	Starting the client will show the loader screen.
	To start the game, open the client console with ~ and type 'connect'.
	You will join the game as spectator, type 'join' in the console
	to join the game. Type 'spectate' to spectate again.
	Type 'disconnect' to return to the loader screen.

	The client is capable of acting as a networked server. You can enable
	the private server by setting 'sv_private 1' before you 'connect'.
	This wil allow remote players to connect to your client.

	To connect to a dedicated server, type 'connect address', where
	adress is the hostname or IP address of the remote server.

	In-game, you can purchase a new ship with the 'buy' command.

Keyboard

	Keyboard controls can be configured with the 'bind' command.
	A key can be bound to an action or a console command. An action
	always starts with a plus or minus sign.

	To bind the keypad left key to the turn left action:

		bind kpleft +left

	To bind the P key to the screenshot command:

		bind p screenshot

	You can use the 'list_binds' command to get a list of currently
	bound keys. Use the 'list_keys' command to get a list of all
	available key names.

	The default configuration:

		~ 		toggle console
		V		switch between track, cockpit and free view
		space bar	turn mouse control on or off
		left right up down arrow 
				rotate camera in free view
		keypad left right up down
				steer the ship left/right/up/down
		keypad / *	roll left/right
		keypad + - 	increase/decrease forward thruster
		T 		open the chat window
		print screen	screenshot

Mouse

	If mouse control is on, you can use it to steer your vessel
	in track or cockpit view, or to rotate the camera in free view.

	If mouse control is disabled, you can temporarily enable it again
	by pressing the left mouse button.

	Use the scroll wheel to increase/decrease thruster.

	Mouse buttons can also be configured through the 'bind' command.

Console functions

	The following commands are available on the console:

		connect		connect the client to the game module
		disconnect	disconnect the client from the game module
		list_ent	list registered entities
		list_func	list registered functions
		list_model	list registered models
		list_var	list registered variables
		quit		exit the application
		r_restart	restart the video subsystem

	The following commands are available when connected to a game:

		join		join the game
		spectate	spectate
		buy		purchase a new ship
		who		list connected players

	To change the video resolution, set the r_width and 
	r_height variables and execute r_restart.
	e.g.: to set the video mode to 1024x768 type:
		
		r_width 1024
		r_height 768
		r_restart

	To switch to fullscreen mode, set the r_fullscreen 
	variable to 1:

		r_fullscreen 1
		r_restart

	You can set your name and player color through the cl_color
	and cl_name variables. Note that your ship's colour won't 
	change until you buy a new one.

		cl_name SpaceCowboy
		cl_color 1.0 1.0 0.0
		connect

Statistics

	To activate statistics, set the draw_stats variable to 1:

		draw_stats 1

	This will draw the following statistics on the right side
	of the screen:

		fps		frames per second
		tris		number of triangles drawn
		quads		number of quads drawn
		tx		network upstream traffic, in kilobyte
		rx		network downstream traffic, in kilobyte

	The fps counter will not show values above 9999.

Configuration

	Variables marked with the 'A' flag will be archived, their value 
	will be written	to the configuration file on exit. The dedicated
	server reads its configuration from server.cfg, the client
	will use client.cfg. Keyboard binds will be saved to binds.cfg

	On UNIX systems you can find these files in the ~/.osirion/base
	directory.

	If you delete these files, the default configuration will be restored.


Dedicated server

	By default, the dedicated server will accept incoming connections 
	on UDP port 8042. There is no server console.

	If you have trouble connecting, try editing the server configuration
	file server.cfg and change the net_server setting to
	the server's actual IP address. The default listening port can 
	be altered by changing the net_port setting.

Command line

	Both the client and the dedicated server can parse command line 
	options. Any console command can be added to the command line with + sign.

	To start a client and connect to a remote server:

		src/osirion +connect remote.server.org

	To start a client and create a new network game:

		src/osirion +set sv_private 1 +connect +join

	To start a dedicated server and set the server framerate to 30 frames per
	second:

		src/osiriond +set sv_framerate 30

	Note:

	Setting variable values from the command line can result in weird values being 
	written to client.cfg and server.cfg. If you run into problems, check those 
	files or delete them.

Note for windows32 users

	On windows32, the game uses the 'home' subdirectory as your personal
	directory. For example, the client.ini can be found in 
	home\base\client.ini. 

	There is also a problem that prevents the game from creating directories.
	If you need any subdirectories in your personal folder, like 'screenshots',
	you will have to create it manually.

Organization of the distribution

	C++ source code

	/src
		README			this file
		INSTALL			documentation in installation
		MODELS			documentation on creating models

		/math			mathematical classes
		/sys			low-level system functions
		/filesystem		virtual filesystem library
		/core			game-independent core library
		/game			game-specific functions 
		/server			osiriond dedicated server
		/render			render library
		/client			osirion client

	Data files

	/data
		/base			game data files
			/bitmaps	essential bitmaps
			/ini		ini files
			/maps		.map models
				/satellites	sattelites
				/ships		spaceships
				/stations	space stations
			/scripts	gtkradiant shader files
			/textures	textures
		/gtkradiant		gtkradiant support files
	
	The game data can be obtained as a seperate distribution.
	Refer to the file INSTALLATION for more information.

Editing game data

	One of the goals of the Osirion Project, is to create an engine
	that makes it very easy to adapt and extend the game world. 
	At the moment, the game reads the world description from 
	ini/world.ini and a list of buyable ships from ini/ships.ini.

	I recommend you do not edit the original game data, but to make a copy
	into your personal osirion folder '~/.osirion'. This directory mimics
	the directory structure of the 'data' directory and any file found
	there will get precedence over the corresponding file in 
	the game data directory.

	The models are basic Quake2 style .map files with custom entities
	and can	be created with a program like gtkradiant. Refer to the 
	file MODELS for more information on creating 3D models.

Project contributors

	[mDc]Thorn	- Canasta and Sharkan ship models, alpha testing

	Josky=KCT=	- Shuttle ship model, alpha testing

	[mDc]Minisori    
	Gareth		- Alpha testing
	DVSoftware
IRC

	The official Osirion IRC channel is #osirion on irc.soliter.org

Web

	Screenshots can be found at 
	http://ingar.satgnu.net/osirion

Acknowledgements

	This project could not have been possible without the work of others:

	Id Software, for releasing the quake source code

	Id Software and the GtkRadiant project contributers

	The Quake2World community

	The Satgnu crew

	Thanks to bobke and blaze-x
	
	DVSoftware for bandwidth, diskpace and CPU power

	A special thanks to all =KCT= members
	
License

	The Osirion Project is distributed under
	the terms and conditions of 
	the GNU General Public License version 2.

	This includes the source code, project documentation and game data.

	Copyright 2007-2008
	Ingar=KCT= <ingar@telenet.be>

	Contact me if you want to use (portions of) this project
	under a non-compatible, but otherwise free, licence.
	
Trademarks
	 
	QUAKE and ID are registered trademarks of Id Software, Inc.
	LEGO is a registered trademark of the LEGO Group.
	
	The Osirion Project is an independent not-for-profit project 
	and has no affiliation with these companies.