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

Help:Values: Difference between revisions

From ModEnc
Jump to navigation Jump to search
CnCVK (talk | contribs)
TAK02 (talk | contribs)
m As requested: the link to BobingAbout's and pd's RGB2HSB converter. On a side-note: we might want a PPM/ModDB link made too just in case.
 
(9 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{BigHorizontalBar|Incomplete|This page is not complete yet. For example, there are still Locomotors and probably other value types. If you are familiar with this topic, please help us by expanding this page.}}
Each [[:Category:INI_Flags|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.


When referring to possible values in flag-headers, ModEnc contributors often use programming or mathematic terms to describe the values you can add.
[[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.


If you are not familiar with these terms, this page should give you an idea about what these different data types stand for and what values [[TD]], [[RA]], [[TS]], [[RA2]] and [[YR]] would accept as such.
==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.


==[http://en.wikipedia.org/wiki/Signedness Signed/Unsigned]==
In the [[INI]]s, negative numbers are written by prefixing them with a hyphen (-). For example, {{f|InitialAmmo|link}} accepts '''signed''' integers[[{{PAGENAME}}#Integers|{{sup|{{arr|d}}}}]]. Thus, <code>InitialAmmo=-2</code> sets the value to &minus;2.
{{tocright}}
For flags expecting numbers, this prefix tells you whether you can use negative values or not - "sign" refers to the minus and imaginary plus in front of numbers. If a value is marked "unsigned", it doesn't accept signs, and therefore you cannot use negative values (as you'd have to apply a sign, minus, to make it negative).


Signed == Positive and negative values<br>
==Value types==
Unsigned == Positive values only


==[http://en.wikipedia.org/wiki/Integer Integers]==
===Integers===
Theoretically, all natural numbers, their negatives, and zero. According to pd, the actual programming data type used by the games is often [http://en.wikipedia.org/wiki/Long_integer signed long integer], with a notable exception being [[ExtraLight]], which only uses [http://en.wikipedia.org/wiki/Integer_%28computer_science%29 integer]; the difference is the maximum size of the number they can hold:
'''Integer''' data types represent a predetermined range of natural numbers. As a value type, '''integers''' can be either signed[[{{PAGENAME}}#Signedness|{{sup|{{arr|u}}}}]] or unsigned, and ''short'' or ''long''.


'''Signed long''' values can be any integer (mathematically) from '''-2147483648''' to '''2147483647'''.<br>
{|class="table_descrowdesccol" cellpadding="5"
'''Integer''' values, the programming data type, can "only" be mathematical integers from '''−32768''' to '''32767'''.
!
!signed
!unsigned
|-
!short
|&minus;32,768 to 32,767
|0 to 65,535
|-
!long
|&minus;2,147,483,648 to 2,147,483,647
|0 to 4,294,967,295
|}


==[http://en.wikipedia.org/wiki/Floating_point Floating Point Values]==
Most [[:Category:INI_Flags|INI flag]] that take '''integers''' accept ''signed long integers''<!--, according to pd-->. One notable exception is {{f|ExtraLight|link}}, which accepts ''short signed integers''.
Or "floats", for short, are basically '''[http://en.wikipedia.org/wiki/Real_number real numbers]''', 3.141592654 (Pi) for instance.<br>
Technically, one would have to differ between floats and doubles (double-precision floating point values), though as INI flags, there is no noticeable difference.
Something special about this value type is that - if your value is between 0 and 1/-1 - you can leave out the 0 before the dot.<br>
So RechargeTime=0.01 would result in the same as RechargeTime=.01.


An example for a float INI tag is the [[RechargeTime]] tag.
Flag values should be without commas and negative numbers should be prefixed with a hyphen: &minus;5,387 should be entered as <code>-5387</code>.


==[http://en.wikipedia.org/wiki/Byte Bytes]==
====XYZ====
In very rare cases, the game (assuming [[YR]]) does only accept bytes as a value.<br>
This is sometimes also called ''point3d''. Like colors[[{{PAGENAME}}#Colors|{{sup|{{arr|d}}}}]], '''XYZ''' is not a true data type, rather a comma-separated list of three ''signed integers''[[{{PAGENAME}}#Integers|{{sup|{{arr|u}}}}]].
Bytes are comparatively small numbers, which often have values less than 20.<br>
Usually, these bytes are unsigned.


While<br>
This value type is used for certain [[:Category:INI_Flags|INI flags]] in the {{ts}} and {{ra2}} [[engine]]s to represent a single coordinate in pseudo-3D space, which is measured in [[lepton]]s. Each integer represents distance in leptons along the X, Y, and Z axes, respectively.
'''unsigned''' bytes can be any integer (mathematically) from '''0 to 255''',<br>
'''signed''' bytes go from '''-128 to 127'''.


An example using this type is the [[CloakRadiusInCells]] tag.
An example of a flag that accepts '''XYZ''' is {{f|ExitCoord|link}}.


==[http://en.wikipedia.org/wiki/Truth_value Boolean values]==
===Floating Points===
A boolean value is a "yes" or "no" value, usually stored as 0 or 1 ("no" or "yes") in a byte.
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, &minus;0.8, and 3.67829.


In the [[INIs]], no matter what some people think, it does not matter whether you type '''yes''', '''true''' or '''1''' - if the value is one of those three, it will be considered '''"yes"''', otherwise, it will be considered '''"no"'''.<br>
{|class="table_descrow" style="float:right; margin-left:10px; text-align:center;" cellpadding="5"
So you could just as well go ahead and type e.g. "[[Capturable]]=no way!" and it would work just fine.
!float
!double
|-
|3.4{{sup|&plusmn;38}}<br />(7 digits)
|1.7{{sup|&plusmn;308}}<br />(15 digits)
|}


An example INI flag would be [[Radar]]=yes/no.
'''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{{sup|&plusmn;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&mdash;1.7{{sup|&plusmn;308}}, or about 15 decimal digits.


==[http://en.wikipedia.org/wiki/String_%28computer_science%29 Strings]==
Most [[:Category:INI_Flags|INI flags]] that take '''floats''' accept ''doubles''<!--, according to DCoder-->, 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 <code>890001.35</code> will simply round up to 890001. Similarly, <code>734.967623</code> rounds to 734.968.
Strings are simply put '''texts'''. On ModEnc, this data type is often followed by a restriction, like "String (names of animations)". Adhere to these restrictions, or get ready for the consequences.


==[http://en.wikipedia.org/wiki/LSD#Sensory.2Fperception Colors]==
Flag values should be without commas and negative numbers should be prefixed with a hyphen: &minus;5,387.036 should be entered as <code>-5387.036</code>. It should also be noted that the leading 0, for values between &minus;1 and 1, is optional; &minus;0.25 can be entered as <code>-0.25</code> or simply <code>-.25</code>.
Colors are nothing but a list of 3 bytes (see above), seperated by a comma (example: [[SovietLoad]]=0,235,255).
There are two color formats (in [[TS]], [[RA2]] and [[YR]]):


===[http://en.wikipedia.org/wiki/RGB RGB]===
An example of a flag that accepts '''floats''' is {{f|RechargeTime|link}}.
The most common way to clearly represent a color is in the RGB format.<br>
It consists of 3 bytes which represents the amount of the basic colors in this order: '''red''', '''green''', '''blue'''.<br>
The RGB format is used, for instance, on the [[RadColor]] tag.


===[http://en.wikipedia.org/wiki/HSV_color_space HSB]===
===Bytes===
HSB appears more rarely than RGB.<br>
Like integers[[{{PAGENAME}}#Integers|{{sup|{{arr|u}}}}]], '''bytes''' represent a predetermined range of natural numbers. However, a '''byte''' only occupies 8 bits (a single byte) in memory, hence the name.
The 3 bytes represent '''hue''', '''saturation''' and '''brightness'''.<br>
[[TS]], [[RA2]] and [[YR]] have a unique HSB format which does not work the same way as e.g. the HSB format in MS Paint does.<br>
There is no clear algorithm yet that can convert [[Westwood]]'s HSB format to RGB or vice versa ([[BobingAbout]] created a pretty exact one, a conversion tool was available and will be available again soon).<br>
This unique HSB format is used in the [<tt>[[Colors]]</tt>] section.


==[http://en.wikipedia.org/wiki/CLSID CLSIDs/Locomotors]==
Usually '''bytes''' are signed[[{{PAGENAME}}#Signedness|{{sup|{{arr|u}}}}]], but they can also be unsigned.
Commonly seen as [[Locomotor]]s, CLSIDs are also used for [[AI Generals]], for example. They are in registry format.


An example would be the ship locomotor, {2BEA74E1-7CCA-11d3-BE14-00104B62A16C}.
{|class="table_descrow" cellpadding="5"
!signed
!unsigned
|-
|&minus;128 to 127
|0 to 255
|}


==POINT3D==
Negative flag values should be prefixed with a hyphen; &minus;30 should be entered as <code>-30</code>.
Coordinates in [[leptons]](1/256th of a cell).<br>
 
The 3 signed integers represent '''X''', '''Y''' and '''Z'''.<br>
In very rare cases, the {{ts}} and {{ra2}} [[engine]]s have flags that only accept '''bytes''' as opposed to integers. One example is  {{f|CloakRadiusInCells|link}}.
An example for a POINT3D INI tag is the [[ExitCoord]] tag.
 
====Colors====
A '''color''' is not a truly distinct data type, rather a comma-separated list of three ''unsigned bytes''[[{{PAGENAME}}#Bytes|{{sup|{{arr|u}}}}]]. 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 {{ts}} and {{ra2}}, each flag that accepts '''color''' value types was designed for one of two color models:
 
=====RGB=====
'''R'''ed, '''g'''reen, and '''b'''lue, is the most common way colors are represented. Each byte[[{{PAGENAME}}#Bytes|{{sup|{{arr|u}}}}]] represents the amount of each color respectively, with 0 as the minimum and 255 as the maximum.
 
This color model is used with {{f|RadColor|link}}, for instance.
 
=====HSB=====
'''H'''ue, '''s'''aturation, and '''b'''rightness, is used much less frequently than RGB[[{{PAGENAME}}#RGB|{{sup|{{arr|u}}}}]]. Similarly, each byte[[{{PAGENAME}}#Bytes|{{sup|{{arr|u}}}}]] represents the amount of each factor. However it is {{co|'''important'''|red}} to note that the {{ts}} and {{ra2}} [[engine]]s 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 {{sl|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 [[INI]]s, a '''boolean''' value of ''true'' can be represented by the literals {{tt|yes}}, {{tt|true}}, or {{tt|1}}; while {{tt|no}}, {{tt|false}}, and {{tt|0}} convert to ''false''. Even if one were to set {{f|Capturable|no way!|link}}, it would still be considered ''false''.
 
Examples of flags that take '''booleans''' are {{f|Radar|link}}, {{f|Armory|link}}, and {{f|Insignificant|link}}.
 
===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, {{f|HoldsWhat|link}} 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 {{f|Armor|link}}, 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. {{f|Explosion|link}} takes a comma-separated (with optional whitespace) list of [[Animations]], while {{f|Sounds|link}} 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 {{ini|rules}} primarily for [[locomotor]]s, but also for [[AI_Generals|AI generals]].
 
==References==
* [http://en.wikipedia.org/wiki/Real_number http://en.wikipedia.org/wiki/Real_number]
* [http://en.wikipedia.org/wiki/Natural_number http://en.wikipedia.org/wiki/Natural_number]
* [http://en.wikipedia.org/wiki/Data_type http://en.wikipedia.org/wiki/Data_type]
* [http://en.wikipedia.org/wiki/Signedness http://en.wikipedia.org/wiki/Signedness]
* [http://en.wikipedia.org/wiki/Primitive_type http://en.wikipedia.org/wiki/Primitive_type]
* [http://en.wikipedia.org/wiki/Integer_%28computer_science%29 http://en.wikipedia.org/wiki/Integer_(computer_science)]
* [http://en.wikipedia.org/wiki/Long_integer http://en.wikipedia.org/wiki/Long_integer]
* [http://en.wikipedia.org/wiki/Floating_point http://en.wikipedia.org/wiki/Floating_point]
* [http://en.wikipedia.org/wiki/Single_precision http://en.wikipedia.org/wiki/Single_precision]
* [http://en.wikipedia.org/wiki/Double_precision http://en.wikipedia.org/wiki/Double_precision]
* [http://en.wikipedia.org/wiki/Byte http://en.wikipedia.org/wiki/Byte]
* [http://en.wikipedia.org/wiki/Boolean_datatype http://en.wikipedia.org/wiki/Boolean_datatype]
* [http://en.wikipedia.org/wiki/RGB http://en.wikipedia.org/wiki/RGB]
* [http://en.wikipedia.org/wiki/HSV_color_space http://en.wikipedia.org/wiki/HSV_color_space]
* [http://en.wikipedia.org/wiki/CLSID http://en.wikipedia.org/wiki/CLSID]
* [http://en.wikipedia.org/wiki/String_%28computer_science%29 http://en.wikipedia.org/wiki/String_(computer_science)]


[[Category:INI Flags]]
[[Category:General Editing Information]]
[[Category:General Editing Information]]

Latest revision as of 19:42, 23 November 2017

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