list of environment variables

{{under construction}}

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.

<div style="float:left; margin-right:1em">
__TOC__
</div>

 ;An example SOM file should appear in this space.

<br style="clear:both" />

==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 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 [[Wikipedia:Windows Registry|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%
<br />

==Work & play==
These variables establish from where the project or game draws its profiles: eg. [[PRF]] and [[PRT file]]s. 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 file]]s 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 [[texture]]s. 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 file]]s taken from the data folders. If a single + or - statement appears then <u>only</u> 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: [[Wikipedia:Intersection|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.

<fieldset><legend>The following sets have special meaning:</legend>
*'''of'''/'''for''': while not technically required, all profiles should belong to either an "of" set or a "for" set. The former includes '''o'''riginal '''f'''iles, while the latter includes expansion files, or '''f'''iles '''o'''f '''r'''elation. If the first rule of DATASET is +of/for then you begin a [[Wikipedia:blacklist (disambiguation)|blacklist]] (instead of a "whitelist".)
*'''items''': is the set of all [[PRF file]]s that are 88 bytes large, traditionally housed in the data/item/prof directory.
*'''props''': is the set of all PRF files that are 108 bytes large, traditionally housed in the data/obj/prof directory.
*'''magic''': is the set of all PRF files that are 40 bytes large, traditionally housed in the data/my/prof directory (and likely to be expanded to include the contents of the data/sfx/Sfx.dat file in one form or another.)
*'''pieces''': is the set of all [[PRT file]]s (228 bytes large) traditionally housed in the data/map/parts directory.
*'''parts''': is the set of all PRF files that fall into the byte size range (between 384 and 564) of the files traditionally housed in the data/npc/prof directory.
*'''evils''': is the set of all PRF files that fall into the byte size range (greater than 564) of the files traditionally housed in the data/enemy/prof directory.
''(On items-props-magic-spots-parts-evils: these names were deliberately chosen to be both meta and abstract, and are intended to evoke a sense of stagecraft, or movie-magic. Take care to not confuse parts&mdash;data/npc/prof&mdash;and pieces&mdash;data/map/parts.)''</fieldset>

'''Note: that set names and file names herein are case-sensitive. Not all system are case-insensitive like [[Wikipedia:Windows|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==
===SCRIPT===
===FONT===

==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 [[Wikipedia:Windows Explorer|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 [[Wikipedia:INI file|INI file]]s 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.)

[[Category:Sword of Moonlight]]