Rapture Manual

Iron Realms Entertainment

Configuration

Most of the behavior of Rapture can be customized through command line options or (preferably) through a specified configuration file. Each configuration option that can be specified in the file can be set by prefixing ‘--’ to the name of the option and following it immediately by the value on the command line. Values specified in this way override any values already set by a config file. For purposes of this document we will assume all values are being set by the file mechanism.

Summary

Configuration	Most of the behavior of Rapture can be customized through command line options or (preferably) through a specified configuration file.
Set Config Options	To set the options via a config files, simply create an empty text file (using your favorite text editor) and set the options, one per line.
The Key File	Upon startup, the Rapture Runtime Environment looks for a valid key file in the current directory named rapture.key (or elsewhere if the KeyFile option has been specified).
The main() Procedure	In order to tell Rapture where to begin executing, you provide a subroutine named main() in your executable somewhere, Rapture finds this and begins execution there.
Config Options	This is a list of the options that can be set in the config file for the Rapture Runtime Environment.
License Authentication	Rapture requires a valid license to run.
Sample Config File

Set Config Options

To set the options via a config files, simply create an empty text file (using your favorite text editor) and set the options, one per line. It simply parses each line and tries to set the first word (non-whitespace chunk of characters) to the value immediately following it on the rest of the line. If the first character of the line is a ‘#’ or the entire line is blank, then the entire line is treated as a comment and is ignored.

The -c option may be used on the command line to tell Rapture to load a configuration file:

$ rapture -c <config file>

or alternately, each option can be specified on the command line

$ rapture -<option> <value>...

Either way, the only option that absolutely must be set is the Executable option. This must point to the executable that needs to be run when ready to do so. Without it, Rapture has nothing to do and simply quits immediately (well technically it looks for a default of rapture.out but nobody uses that).

The Key File

Upon startup, the Rapture Runtime Environment looks for a valid key file in the current directory named rapture.key (or elsewhere if the KeyFile option has been specified). This checks for license integrity, expiration date, etc. If any of this should fail, Rapture will be unable to start. Upon passing all these tests, the code is loaded, databases opened, and execution begun.

The main() Procedure

In order to tell Rapture where to begin executing, you provide a subroutine named main() in your executable somewhere, Rapture finds this and begins execution there. Rapture will then only exit when too many errors have been generated or you return control from that main subroutine. If the reload() internal routine has been called prior to returning from main(), then the executable will be unloaded and loaded again (from the hard drive) and the process will begin again. All of this will happen without losing any database or network connections and allows a swapping in and out of the game logic and mechanics at runtime. This ``warm boot’’ is greatly advantageous in systems which cannot be shut down and run 24 hours a day. For example, a program can use this to implement new features and fix bugs all invisibly to any users currently connected to the system.

Config Options

This is a list of the options that can be set in the config file for the Rapture Runtime Environment.

LicenseAuth	This specifies the location of the license authority used by Rapture to authenticate your copy of Rapture and to verify the integrity of your key file. The format is <address>:<port>. This information will be provided by Iron Realms upon purchase of a valid Rapture license.
KeyFile	Use this to specify a location other than the default (rapture.key in the current directory) for the key file.
DataFile	Specify the name of the single file containing all databases. Note that this includes a path if there is one (and DataDir does not affect this option).
DataDir	This is the old method of specifying where data files should be written. Some features stil use this however, so it must be present. Usually this is simply the directory where your DataFile option is at.
Executable	The filename of the executable that should be run. A executable in Rapture is a .rx file.
Port	The Unix port number that Rapture should bind as the server port. Clients may then connect to the machine running Rapture on the port specified. Note: You must be the root user on your system if you wish to bind a port below 1024.
ErrorLog	Specify a filename for a log of any errors generated while running.
SysLog	Specify a filename for a log of any informative messages generated by Rapture while running.
Passive	A positive integer indicating the ‘passivity’ of Rapture while running. The passivity affects performance and task latency by attempting to sleep when there is no input waiting and no tasks are due for execution. This is provided so that development can be done on a single processor machine with minimal impact on the system. A value of 0 will disable this and Rapture will run at maximum speed (this is the default). A higher value will decrease the system processor usage at the cost of task latency (firing tasks will be late).
MaxPerIP	An integer indicating the number of connections from any specific IP address that Rapture will allow. The default is 5.
RXPath	This is used to specify the path of the IPC message queue used when communicating with Rapture via the IPC rmqtool program. This option need only be used when multiple rapture servers are running and each must have a separate message queue. See <IPC> for more information. The default is “/tmp/.rapture-RX000”.

License Authentication

Rapture requires a valid license to run. When Rapture starts up, it looks for a file called rapture.key in the current directory. (Or another location if specified using the KeyFile config option). This key file contains information necessary to validate your license and permit Rapture to run normally. Rapture checks and performs validations automatically as long as the key file is present. If it is not, Rapture will interactively ask for both a license number and an activation code to be used in generate the key file. Once your license information has been authorized, Rapture will start up normally.

The initial authorization screen will look something like the following.

Rapture Runtime Engine v1.2.0 - Copyright (c) 2002 - Iron Realms Entertainment
A valid key file must be obtained from the Rapture License Authority,
to do so requires a license number and activation code. By entering
this information here, you agree that you are the valid license holder
and are bound by the terms of your License Agreement with Achaea LLC.
Please direct questions to rapture@achaea.com

Press Control-C to quit...

License No. (XXX-XXXX-XXX): 999-9999-999
Activation Code (case sensitive): abcdef1234

Sometimes it is necessary for you to specify the location of the license authority so that your license may be authorized for use. This may be done using the LicenseAuth config option. Note that the format for this option is: <host address>:<port>. Example: achaea.com:28028. This information will be provided when you obtain your license.

Sample Config File

# KeyFile:
#     Necessary to boot up Rapture

KeyFile        rapture.key

# LicenseAuth:
#     The location of the license authority. In "name:port" format.

LicenseAuth    achaea.com:28080

# DataDir:
#     This specifies what path the database files should use.

DataDir        data
DataFile       data/achaea.data

# Executable:
#     This points to the game code compiled by Rapture.

Executable     game/achaea.rx

# Port:
#     This tells rapture what port to bind upon starting (Note that
#     binding ports lower than 1024 requires root permissions).

Port           2000

# ErrorLog:
#     File to log errors to.
ErrorLog       err.log

# SysLog
#     Log system messages such as bootup, crashing (hopefully), etc
SysLog         sys.log