SOM file/list of environment variables

Note that while this article is divided into sections, the SOM file itself is not. It is essentially an INI file but were it actually such it would be an INI file without sections. It is best to think of it as a radically simplified BAT file where environment variable assignment eschews the SET command and nothing else works. Refer back to SOM file.

It should be possible to spread variables across multiple lines by recognizing an = followed by nothing as the beginning of a multiple line assignment. Assignment should continue until a line comprised of nothing or all spaces is encountered. Many variables that accept file system addresses should support multiple addresses separated by ; or the end of a line. An address should not be allowed to spread itself across multiple lines, however multiple addresses may be spread across multiple lines.

Care should be taken to leave the first line after an = in a multiple line assignment blank, or else it should be interpreted as a single line assignment.

;An example SOM file should appear in this space.

Identification

GAME and DISC are unique in representing the original content of the .SOM file. If the first or second line does not begin with a ; or contain an = then they should be interpreted as assignment to GAME and DISC respectively.

GAME

GAME is a label used to identify a physical or virtual media, such as a compact disc. It does not have to be a legal file name, but if it is to be used elsewhere, it ought to be.

If CD is used to change to a physical or virtual drive with SOM files, then the first file should be checked to ensure that GAME and #DISC match. If they do not then the user will be advised that the incorrect media may be inserted into CD. Refer to #CD.

DISC

DISC is used for an additional level of virtual disc identification. It could be changed for every variant of a disc. Or even made unique for ever printing of a disc. Refer to #GAME.

Information

These variables are not variables as such as assigning values to them accomplishes nothing special. In other words these are simply informational variables. If you do not substitute them into other variables by way of surrounding them in percent signs they will not be otherwise used for any other purpose.

SOM

SOM communicates the name of the project. It defaults to the full address of the SOM file itself. This name should only be used locally on a computer, for instance in the computer's Windows Registry database, or within temporary files. If SOM is not assigned, or empty, then software should assume that a SOM file has not been made available.

Note: that SOM is noted as part of the core specification. It is of no practical use within the SOM file itself, but is important to software development. Still it may be useful to override SOM with a new value as long as it is never made empty under any circumstances.

TITLE

TITLE is the name of the executable file or SOM file or other mechanism used to run a game program. The dotted extension part of the file name is removed from TITLE. Since TITLE is necessarily a legal file name it may be used along with #PLAYER in order to generate a #USER folder if the default user folder is not a directory or is read-only, for instance a compact disc, or CD-ROM.

A program may prefer to use #GAME over TITLE for this purpose, however TITLE is provided as a fallback mechanism. GAME is not required to be defined and may not be a legal file name. The player may be prompted to create the user folder and edit the name as necessary to produce a folder that works for them, or choose an entirely different folder.

PLAYER

PLAYER communicates the player's folder. This may be a setting or a default folder, for example the Saved Games folder of Window's Vista. Note that the folder itself is not specific to the game or project. Neither is it the literal save folder:

;on Windows Vista the save folder will be Saved Games/King's Field/save
GAME=King's Field
USER=%PLAYER%/%GAME%

Work & play

These variables establish from where the project or game draws its profiles: eg. PRF and PRT files. Where no profile exists or no profile is discovered files should be searched for according to the classical Sword of Moonlight data directory layout.

Data should be searched for in the following order: #USER/data, #CD/data, #DATA. Generally speaking CD is the top-level game folder. DATA is additional data folders, chiefly of utility to project developers. USER/data should be reserved for use by players and solely for the purpose of customizing the profiles of a game that they are busy playing.

Profiles should be discovered within each and every folder below the data folders including the data folders themselves. If #DATASET exists then only profiles mentioned by any SET files therein should be included.

A single data folder hierarchy should not contain two profiles with the same name and type: differentiated by the size of the files. Where two data folder hierarchies share a profile the hierarchy closest to the top-level, or first in the list of addresses, including USER and CD, override those that follow, however the folders of the overridden profiles should be retained so that external references remain available by default. For example, if a profile A takes the place of profile B. A and B share the same textures. But the texture cannot be located by way of A. So by default the texture should be located by way of B, and so on down the line, C, D, et cetera.

CD

CD should initially be assigned to the folder of the SOM file. If it is assigned to the game's top-level folder changes. In this way a game's files are not required to be in the same folder as the SOM file. The file may be anywhere that is convenient, for example, near the player's save game files. If the game is stored on a read-only media, for instance, a CD-ROM, then it's SOM file and other files could not be modified. By copying the SOM file to another folder it can then be modified. A read-only game may do so automatically when creating its save game folder.

If there are SOM files located in CD, the first two lines of one of them (chosen at random) should be matched against the #GAME and #DISC variables. If there is a mismatch the player should be prompted to confirm this. It may be that the wrong CD-ROM is inserted, or a simple clerical error. CD is expected to be a single address.

USER

USER does not exist initially. If it is not assigned to a folder then #CD should be used unless it is a read-only folder, in which case a default folder that is suitable for save games and customization should be used in its stead. USER is expected to be a single address.

DATA

DATA should initially be assigned to the system wide Sword of Moonlight data folder where Sword of Moonlight is installed. Except for standalone retail games which should initially assign DATA to an empty yet not nonexistent value, such that K%DATA%F becomes simply KF nothing in between.

DATA can be many addresses, however implementations may impose an arbitrary limit upon the number of addresses. Profiles

DATASET

DATASET should only be used by tools to whittle down the number of profiles that will be available to the project.

You might wonder, why not just have every profile available to you? Because A) you can save yourself time by sifting through only the profiles that might make sense to your project. B) some tools must load up every single profile. This can take time, especially over a network. C) you can focus on only the profiles you are interested in as a small part of a larger collaborative project.

DATASET is a single variable. However it is almost definitely a large variable spread out over multiple lines. A multiple line variable begins with an = with nothing to its right, and ends at the first blank line. Technically you can also append to the data set:

DATASET = 
+monsters

;and later on
DATASET = 
%DATASET%
+wildlife

Sets allow lines beginning with + or - or | include individual profiles and or sets of profiles:

;include short swords found within the Cemetery
+Cemetery 
|short swords

A | line continues a + or - line. It is equivalent to appending each | line to the end of the + or - line. In other words the example above is equivalent to:

;include short swords found within the Cemetery
+Cemetery short swords

A - line is an exclusion statement. Comment lines can appear above or below | lines without terminating a + or - statement spread over multiple lines.

While it may be technically possible to place a + or - or even a | in the middle of a line it is not recommend. And no matter what the case a + or - or | statement cannot be spread out across multiple lines. In other words, the end of a line should end the current statement. Lines that do not begin with + or - or | or ; should be regarded as erroneous, ending the data set then and there, unless the line is interpreted as a nonstandard extension.

The words of a + or - statement are found among SET files taken from the data folders. If a single + or - statement appears then only profiles named by SET files can be included in the project.

Instead of an empty space, a / may be used to separate sets. Where a space yields an intersection of two sets, a / yields a union:

;include both short and long swords found within the Cemetery
+Cemetery short/long swords

All / separators are considered before empty space separators. Just as 3*3+4*4 is usually interpreted to mean (9)+(16) and not ((9)+4)*4. (Note that the grouping parentheses are for illustration purposes only.)

Finally, anything with a . in it is interpreted as a literal file name with dotted extension to be matched by files sharing the same name. Several restrictions are imposed upon dotted rules, however the basics can be summed up in the simple maxim: always precede dotted rules with an empty space. In other words they must be: combined with a proper set; they must not be the first listed in the combination; and they cannot take part in slash (/) unions. Note that this rule implicitly bars the appearance of a . in the name of a set.

Playtesting

These variables affect the starting parameters of the game itself.

INI

INI should default to #TITLE.ini. This places the game's INI file in the user folder. Refer to #USER.

TRIAL

TRIAL is the title of an MPX file. The dotted extension should be omitted. TRIAL is not a number. If the file name is 00.mpx, TRIAL should be 00, not 0. TRIAL should be ignored unless the SOM file itself is used to play the game, for example double clicking the SOM file in Windows Explorer.

With all of these conditions met, the SOM file should begin a new test game already on the trial map.

Note: that som_rt.exe does not include a test game feature.

Extensions

These variables are nonstandard extensions.

EX

EX is a list of SomEx cascading Ex.ini file addresses. Folders are ignored. Initially EX is the address of the SOM_EX.ini file located in the working Sword of Moonlight installation's tool folder.

The INI files each take a turn at configuration from the front of the list to the back of the list, so that anything that is configured may be reconfigured by each subsequent file in the list.

If one of these files is located below #CD and there is a name identical file below #USER (were that CD replaced with USER) then the file below USER should be used in place of the file below CD.