Sword of Moonlight Extension Library/editor extensions

Extensions in this section deal exclusively with the editing tools which authors use to make new Sword of Moonlight games. For the most part other sections pertain to tools only in so far as if and when a tool includes previews of in game elements; extensions affecting the project should apply, however in practice this may not always be the case.

assorted...

Introduced around 1.1.2.3, this extension complements #sort_.... Profiles that were not sorted into categories are listed towards the end of the menus in SOM_PRM. With this extension a heading may be applied to these unsorted, or assorted, profiles. The part after assorted may be an underscore (_). Refer to #sort_.... Values are limited to any string of text.[#]

black_saturation

Introduced around 1.2.2.2, this extension is established mainly so end-users may change the contrast levels of text that is overlaid onto background and button graphics. By default the text appears as pure black text over pure white text, separated by 1x1 pixel offsets. The effect is pleasing if monitors have control over "sharpness" and are not set to be overly sharp. Otherwise, reducing the contrast by making black more gray and or white less bright is facilitated by black_saturation and #white_saturation, if and when reducing sharpness is either not possible or not desirable.

The color can be made different for buttons by examining the first parameter, that is "NaN" (not-a-number) for background text, and not-so for button text. This parameter might indicate the button's graphic, or it might not; in which case it is the number 0. Historically button graphics are darker than background graphics, and so might benefit from increased contrast.

These extensions can also be used to experiment with novel themes via the "theme and language package" framework. The functionality is limited right now, but will be expanded to meet demand as it is an appropriate application of these extensions. Values are limited to base 256 identifiers.[#]

clip_volume_multiplier

Introduced around 1.1.1.3, this extension scales the clip volume in the windows where 3D graphics are on display. Scaling by values less than 1 will make objects appear larger, or closer, and scaling above 1 vice versa. 0.5 works very well in SOM_PRM. Values are limited to real numbers.[#]

Note: This extension is currently limited to SOM_PRM.

default_pixel_value

Introduced around 1.1.1.3, this extension effectively changes the background color (normally black) in the windows where 3D graphics are on display. Values are limited to hexadecimal color codes.[#]

do_hide_direct3d_hardware

Formerly do_hide_direct3d_hardware_devices prior to 1.1.1.5

Introduced around 1.1.1.3, this extension will hide any hardware accelerated display devices from Sword of Moonlight tools. If there is no pure software device available then there will be a failure to acquire a device. Use this as a last resort when having compatibility problems. Values are limited to binary statements.[#]

This extension is not intended to be necessary under any circumstances. It is a temporary fallback. If you find yourself relying upon it, please report the difficulties you are experiencing to someone who is in a position to resolve your issue.

do_overwrite_project

Introduced around 1.1.1.4, this extension is nothing fancy. It will let you have Sword of Moonlight create a new project on top of an existing folder where a project may already be found. The normal project template will simply be written over whatever files and folders are in the target folder. Sword of Moonlight will not complain or refuse to do your bidding, neither will you be warned of the impending overwrite. Values are limited to binary statements.[#]

do_overwrite_runtime

Introduced around 1.1.1.4, this extension is nothing fancy. It will let you have Sword of Moonlight create a new runtime on top of an existing folder where a runtime may already be found. Your project will simply be converted and deposited on top of whatever files and folders are in the target folder. Sword of Moonlight will not complain or refuse to do your bidding, neither will you be warned of the impending overwrite. Values are limited to binary statements.[#]

do_subdivide_polygons

It is recommended that this extension NOT be used. It is provided just in case.

Introduced around 1.2.0.8, this extension reinstates the older/original behavior of subdividing level geometry that is beneath lamps. To enable the use of #do_aa the map compiler is made to subdivide everything equally, and because presently per-vertex-lighting is required: maximally. Values are limited to binary statements.[#]

sort_...

Introduced around 1.1.2.3, this extension sorts profiles in SOM_PRM into categories based on SET files. The part after sort_ must be one or more sets separated by underscores (_). An additional underscore may appear after the final set to indicate that a space ( ) should not be appended to the end of the category heading.

By default a space (_) is appended to the heading, and the profile's description follows the space. %s can be written in order to embed the description directly within the heading. Categories appear in the order in which they appear in the INI files. Refer to #assorted.... Values are limited to any string of text.[#]

Since 1.1.2.8 there is limit on the number of sets in play, although this is an implementation detail. And there are two new ways to use sort_:

• sort_x or sort_x= where nothing follows the equal sign (=) causes "x" to be effectively appended to subsequent sort_ directives. To clear the "appendix" just use sort_ by itself; or in other words, append nothing.
• sort_=x causes a separator to be inserted into the resulting categories. If nothing exists between two separators then the first separator will not appear. Separators should be used, and used consistently if so.

Tip: two new examples of how all of this works: [1][2]

time_machine_mode

Introduced around 1.2.2.2, this extension when set to 2000, disables some extensions in order to demonstrate the classic "look & feel" of Som2k. This is intended to demonstrate some esthetic characteristics to researchers, historians, and their like, by offering a middle ground between installing a period specific virtual machine loaded with Sword of Moonlight's original CD-ROM's materials. Values are limited to whole numbers; 0, 2000.[#]

texture_subsamples

Introduced around 1.1.1.3, this extension blows up textures, smoothing them out in the process. So if set to 2, a 256x256 texture will become a 512x512 texture in memory. Sword of Moonlight alone will try to blow textures up to the maximum size allowed by the display device. With modern hardware that is quite dangerous, since 8192x8192 or better is common, which is a 256MB texture. The Sword of Moonlight Extension Library by default uses 256x256 textures. Values are limited to whole numbers; 1, 2, 4.[#]

It's not clear why Sword of Moonlight tools exhibit this behavior. One theory is the tools would in their day require software emulation under most circumstances to display graphics inside popup windows. Since filtering the texture on screen would be slower for a software rasterizer, blowing the texture up achieves the same effect while consuming considerably more memory.

The Extension Library ensures the texture is sampled in "halftone" mode. Sword of Moonlight neglects to do so and therefore where that is not the default behavior will likely consume about 16⁺ times the memory required without any positive effect.

⁺based on standard legacy software device numbers (1024x1024)

white_saturation

Introduced around 1.2.2.2, this extension is established mainly so end-users may change the contrast levels of text that is overlaid onto background and button graphics. Refer to #black_saturation. black_saturation has more to say on this subject. Values are limited to base 256 identifiers.[#]