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.

Verification

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 verify 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 verification. It could be changed for every variant of a disc. Or even made unique for every 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 its 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.

CD must be single absolute file system path. All other paths if relative are appended to CD, without exception. If CD is not the location of the SOM file, then it should be verified against two possible SOM files located inside CD. This is akin to a CD-ROM game verifying that the correctly signed compact disc is inserted into the disc drive. The first candidate is named %CD%/%TITLE%.som. Refer to #TITLE. If the first file name fails, then a file named "CD.som" takes its place.

If neither file exists, or the first two lines of the file, which must be a #GAME line and a #DISC line, do not match then the game program should prompt the player to insert the correct disc. Note that only the first two lines of the second file should be consulted, so that effectively the first file completely replaces the contents of the second.

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 Sword of Moonlight installation's data folder. DATA can be many addresses, however implementations may impose an arbitrary limit upon the number of addresses allowed.

All folders contained by DATA including folders contained by those folders and so on should be searched for profiles, not limited to PRF files and PRT files, taking into account the extensions and footprints (or size in bytes) of the profiles, but not accounting for the names of the folders in which the files are contained.

DATASET

Note: that SETs below are made-up just for example. Sets are a new feature that needs time to establish itself.

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.

Note: that set names and file names herein are case-sensitive. Not all system are case-insensitive like Windows; so you should get used to this. Plus sets may be capitalized proper names, therefore its grammatically incorrect to get that wrong, and in theory there could someday well be two public sets, one capitalized, one not, with two different meanings.

Translating

These variables pertain to writing a game's script, whether that is translating from Sword of Moonlight's original and for the most part inflexible Japanese, translating from simple notes embedded within world maps, translating a game so that it can be more easily appreciated by players who are uncomfortable with the original translation, or translating an existing translation or manuscript in an effort to produce a superior product.

SCRIPT

SCRIPT should not be initially assigned to anything. As it is relative to #CD it defaults to CD.

A script.mo file should be located with SCRIPT, first in the SCRIPT/lang/LC_MESSAGES/ll_CC folder, where ll_CC is a #language and country code pair. And in lieu of that within SCRIPT.

If SCRIPT is not a folder, it should be assumed to be a Gettext MO file. If SCRIPT is a folder, then a font folder should be looked for within SCRIPT. Refer to #FONT.

FONT

FONT should initially be assigned to the Sword of Moonlight installation's font folder. FONT can be many addresses, however implementations may impose an arbitrary limit upon the number of addresses allowed.

If an address is a folder, then everything within it should be consider a font and added to the environment's pool of available font resources. Note that this implies that folders within the folder should not be descended into.

If an address is not a folder, it should be assumed to be a font. This is in addition to #USER/font, #CD/font, and #Script/font. Ordering is assumed to not matter.

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.

Note: if INI is made to be an absolute path, then it cannot be made relative to the user folder. If an absolute INI file cannot be written to then in game options will be lost at the end of play.

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.

SETUP

SETUP selects the profile used to initialize the player character when beginning a new game. Historically SETUP may be 1 or 2, corresponding to the character setup menu of SOM_SYS. If not 2 then SETUP should default to 1.

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.

Note: that USER above is an oversimplification. If the game or USER folder itself is on a read only file system a default user folder should be provided.

ICON

ICON is a path to an icon file, or a file from which an icon can be extracted (the first icon shall be used.)

TEXT

TEXT should initially be assigned to the Sword of Moonlight installation's text folder. TEXT can be many addresses, however implementations may impose an arbitrary limit upon the number of addresses allowed.

A "text" folder is a world language/theme package that is used to translate editing programs including their text and layouts for any purposes. Programs are represented by either EXE or RES files. Only the old programs From Software published along with Sword of Moonlight should be packaged as EXE files. These files are found in the tool folder in the root of the language/theme pack. Data files are located within the data folder and include profiles and project templates. Data files can be either binary files, assumed to be stored in Microsoft Windows code page 932 (nearly identical to Shift-JIS), or Unicode text files.

Care should be taken with TEXT because more commonly the text folder is not itself a language/theme pack, however it is useful to be able to rely on %TEXT% to expand to the text folder wherein typically actual language/theme packs reside. What's more, because TEXT is usually managed by an initial language configuration step, by the time the SOM file has access to TEXT it will more than likely no longer refer to the installation's text folder.

Finally/usually a language/theme pack is an archive, historically PKWARE ZIP files, because that is the format that Windows Explorer supports natively.

Tip: if you need to have two instances of the same program running at the same time using different language/theme packs, or if your project's language/theme package differs from that of the installation (ie. SOM_MAIN) then you may run into problems that can be resolved by changing the TEMP variable within your individual projects' SOM files. The TEMP variable locates the temporary folder for your user account on your computer.