ModEnc is currently in Maintenance Mode: Changes could occur at any given moment, without advance warning.

Help:Values

From ModEnc
Jump to: navigation, search

Each INI flag can only accept a certain data type in each context that it is used. Often, flag values must be formatted in a particular way to be useful to the engine. These formats should be referred to throughout ModEnc as value types.

Template:Values is used for generating standardized descriptions of the various value types accepted by INI flags. This page serves to explain the basic value types in greater detail.

Signedness

Data types representing the real line are signed if they represent a subset of real numbers, negative and non-negative. Likewise, they are unsigned if only representing non-negative numbers—those above and including 0.

In the INIs, negative numbers are written by prefixing them with a hyphen (-). For example, InitialAmmo accepts signed integers. Thus, InitialAmmo=-2 sets the value to −2.

Value types

Integers

Integer data types represent a predetermined range of natural numbers. As a value type, integers can be either signed or unsigned, and short or long.

signed unsigned
short −32,768 to 32,767 0 to 65,535
long −2,147,483,648 to 2,147,483,647 0 to 4,294,967,295

Most INI flag that take integers accept signed long integers. One notable exception is ExtraLight, which accepts short signed integers.

Flag values should be without commas and negative numbers should be prefixed with a hyphen: −5,387 should be entered as -5387.

XYZ

This is sometimes also called point3d. Like colors, XYZ is not a true data type, rather a comma-separated list of three signed integers.

This value type is used for certain INI flags in the Tiberian Sun and Red Alert 2 engines to represent a single coordinate in pseudo-3D space, which is measured in leptons. Each integer represents distance in leptons along the X, Y, and Z axes, respectively.

An example of a flag that accepts XYZ is ExitCoord.

Floating Points

Also called floats for short, floating points are real numbers written in decimal notation without a fixed position for the decimal point. They can represent numbers such as 51.025, −0.8, and 3.67829.

float double
3.4±38
(7 digits)
1.7±308
(15 digits)

Floats are a unique data type because they can represent a number of ranges depending on where the decimal point is located. The range is also limited by how many bits are used to store the data. A single precision float occupies a total of 32 bits (4 bytes), with 24 bits allocated to the significand (the significant digits of the number). The actual range can be written in exponent notation as 3.4±38, which allows about 7 digits, one of which is assumed to be the decimal point. A double precision float, often called a double, occupies 64 bits (8 bytes), with 52 bits allocated to the significand—1.7±308, or about 15 decimal digits.

Most INI flags that take floats accept doubles, though this will rarely make a difference, as extraneous precision will simply be rounded if it will not fit into the allocated space. For example, a single precision float with a value of 890001.35 will simply round up to 890001. Similarly, 734.967623 rounds to 734.968.

Flag values should be without commas and negative numbers should be prefixed with a hyphen: −5,387.036 should be entered as -5387.036. It should also be noted that the leading 0, for values between −1 and 1, is optional; −0.25 can be entered as -0.25 or simply -.25.

An example of a flag that accepts floats is RechargeTime.

Bytes

Like integers, bytes represent a predetermined range of natural numbers. However, a byte only occupies 8 bits (a single byte) in memory, hence the name.

Usually bytes are signed, but they can also be unsigned.

signed unsigned
−128 to 127 0 to 255

Negative flag values should be prefixed with a hyphen; −30 should be entered as -30.

In very rare cases, the Tiberian Sun and Red Alert 2 engines have flags that only accept bytes as opposed to integers. One example is CloakRadiusInCells.

Colors

A color is not a truly distinct data type, rather a comma-separated list of three unsigned bytes. However, they are distinctly formatted and code for visual colors in a predefined way; thus they are included here as well under the alias, colors.

In Tiberian Sun and Red Alert 2, each flag that accepts color value types was designed for one of two color models:

RGB

Red, green, and blue, is the most common way colors are represented. Each byte represents the amount of each color respectively, with 0 as the minimum and 255 as the maximum.

This color model is used with RadColor, for instance.

HSB

Hue, saturation, and brightness, is used much less frequently than RGB. Similarly, each byte represents the amount of each factor. However it is important to note that the Tiberian Sun and Red Alert 2 engines use a unique HSB color model that is not the same as the one used by most PC programs, like MS Paint.

Bobingabout made an RGB-to-HSB color converter. Get it here: http://bobingabout.gamemod.net/Files/rgb2hsb.exe.

This unique color model is used with flags in the [Colors] section.

Booleans

A boolean is a truth value that is either true or false. In computing, this can be stored in one bit as a 1 or a 0, representing true and false respectively.

In the INIs, a boolean value of true can be represented by the literals yes, true, or 1; while no, false, and 0 convert to false. Even if one were to set Capturable=no way!, it would still be considered false.

Examples of flags that take booleans are Radar, Armory, and Insignificant.

Strings

A string, or string literal, is a sequence of characters defined in an alphabetic set. For the most part, this simply means normal text.

The accepted character set includes upper and lower-case letters a to z and A to Z, numerals 0 to 9, as well as hyphens (-) and underscores (_). Whitespace (tabs and spaces) and most other punctuation marks and characters are not allowed.

In most cases, string values are intended to point to an ID of a certain object class. For example, HoldsWhat can only take an ID of an existing Particle class object.

A few flags take string values that must be formatted in a certain way. These values are referred to as being hardcoded because they are only accepted if they match the predefined format. One example is Armor, which accepts different strings depending on the game engine.

Furthermore, some flags take a list of strings, separated by whitespace and possibly a distinct, separator character. Explosion takes a comma-separated (with optional whitespace) list of Animations, while Sounds takes a whitespace-separated list of VocTypes.

CLSID

This is often referred to as a locomotor, but the technical name is CLSID, which stands for class identifier. As a subtype of GUIs (globally unique identifiers) it is stored in the registry and serves to reference a specific class in any context that it is used.

CLSIDs are written as a sequence of hexadecimal digits, enclosed in braces, and hyphens are added to separate fields:

{4A582742-9839-11d1-B709-00A024DDAFD1}

These are used in rules(md).ini primarily for locomotors, but also for AI generals.

References