Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
69 lines (38 sloc) 3.55 KB

Conventions

Content

Information in these documents MUST be verifiable, or have been verified (e.g. through testing or cross-reference to original code) to be included. Assumptions, contradictions, discussions and the like MUST be handled through the issue system.

In general, changes to the documents SHOULD be introduced by linking commits to corresponding issues. This way, issues can be used as reference material for verification.

Language

The human language of this documentation is English. Names of types/fields SHOULD follow that of the source (which is presumably en-us), while prose text SHOULD follow en-uk .

This is primarily to uphold the legacy of this documentation. The original ss-specs was maintained within the context of TSSHP, which came from Britain.

When wording actions, consider differenciating between the character in the game-world ("the hacker"), and the player. ("The hacker has a rotation angle of xyz, so the player sees...").

Sentences referring to individuals SHALL be phrased with inclusive, gender neutral language. The use of singular they is to be used if no other option is available.

While the hacker is represented with a male body and voice in the original game, a fan-mod could change this. This documentation states raw engine data, which doesn't care about humans, even if considered to be insects.

Formatting

Vanilla Markdown SHOULD be used for all pages.

The biggest header available is the H2 header (""## Title"). H1 header are reserved for the main title. Each page SHOULD start with an H2 header, which is also the link in the index.

Data

In general, this documentation describes (serialized) data structures. Such data structures SHOULD be documented using code blocks and follow the following format:

offset  type  description

Example

0000  int32     some value
0004  [14]byte  unknown, not used (0x00)
0012  int16     other value

Offset values MUST start at 0 and be given in hexadecimal (or placeholder). They SHOULD have a width of 4 (or more) digits.

Types are field specific.

Description is a short human-readable text describing the field.

Integers

For integer types, they MUST be given in the following format:

(s|u)?int(8|16|24|32)

's' and 'u' prefixes specify 'signed' and 'unsigned integer' respectively. If no sign-prefix is given, it has not been verified whether this field allows negative values or allows greater positive values.

Implementors MAY treat fields without known sign to be unsigned - this can be the case for length fields for instance. It is unknown whether the original executable would handle them correctly.

Unless otherwise noted, integer values are stored in little-endian format.

Fixed point numbers

Due hardware limitations and slow perfomance of float point operations, System Shock uses fixed point number represenation of real data type. Usually engine uses Q15.16 format (1 bit for sign, 15 bits for integer part, 16 bits for fractional):

0x 0000 0000
   |    |
   |    fractional part
   integer part with sign (first bit, 0 means positive, 1 - negative)

This format is refered as fix (int32). For example, (2 * Pi) number is 0x0006487f (6 + 18559/65536 = 6.28319)

Internally engine supports Q23.8 numbers (fix24) or even Q2.28 (for some 2D- and 3D-computations).

You can’t perform that action at this time.