Bitmask Type Reference
A bitmask is a data type that encodes multiple independent true/false conditions inside a single integer value. In Unturned™ modding, bitmasks appear in configuration files where the engine needs to track several simultaneous states without allocating one field per state. A single integer field can represent up to thirty-two distinct binary conditions (one per bit in a thirty-two-bit integer), each independently on or off, by treating each bit position as a separate toggle.
57 Studios™ has documented and validated the bitmask type across the Unturned™ modding configuration surface. This article covers the binary representation that underlies every bitmask, the integer and hexadecimal formats accepted by the parser, the weather ambience volume example from the official Smartly Dressed Games documentation, the relationship between bitmasks and enum flags, and the bitwise operations that mod developers use to read, write, and test individual bits within a bitmask value.
Documentation source: This article references the official Smartly Dressed Games modding documentation chapter on bitmask types and the weather ambience volume example. The binary arithmetic sections are cohort-validated explanations of bitwise operations as they apply to the Unturned parser.
Who this article is for
This article is written for Unturned™ mod developers who have encountered bitmask fields in configuration files or the official documentation and need a complete working understanding of how bitmasks function, how to read them, how to write them, and how they relate to the flag and enum types that also appear in the .dat file format. Readers should already have working familiarity with the .dat file syntax, the concept of integer and flag types, and the general structure of Unturned item and object configuration. If you are new to the .dat file type system, start with the data-types section index before returning here.
Background: the binary representation
Every integer value stored by a computer is represented as a sequence of bits, each bit being a single binary digit that holds either 0 or 1. A bitmask interprets each bit position as an independent on/off toggle rather than as part of a combined numeric value. The integer 3 in ordinary arithmetic represents the quantity three. The integer 3 in bitmask arithmetic represents bits 0 and 1 set to 1 and all other bits set to 0 , two independent toggles in the on position, encoded into one number.
The bit positions in an eight-bit value are arranged as follows, with bit 0 as the least significant bit (rightmost) and bit 7 as the most significant bit (leftmost):
Bit position: 7 6 5 4 3 2 1 0
Bit value: 0 0 0 0 0 0 1 1 = decimal 3
Bit 0 = 1 (value 1 = 2^0)
Bit 1 = 1 (value 2 = 2^1)
Bits 2-7 = 0When bit 0 is set to 1, it contributes a value of 2^0 = 1 to the integer. When bit 1 is set to 1, it contributes 2^1 = 2. When both are set, the integer value is 1 + 2 = 3. When only bit 0 is set, the integer value is 1. When only bit 1 is set, the integer value is 2. When neither is set, the integer value is 0.
This mapping , one bit per independent condition, with each bit contributing its position's power of two to the integer , is the entire mechanism of the bitmask type. There is no additional encoding layer between the integer value and the set of conditions it represents. The integer 3 always means bits 0 and 1 are set; the integer 5 always means bits 0 and 2 are set (values 1 + 4 = 5); the integer 0 always means no bits are set.
As shown in the flowchart above, a single integer value decomposes into multiple independent on/off conditions through the binary representation. The parser treats the integer as a bitmask whenever the field is documented as a bitmask type, and it reads each bit position independently.
Relationship to powers of two
The value contributed by each bit position is a power of two. The table below lists the decimal value of each bit position in a standard unsigned eight-bit integer, which is the smallest container that the Unturned parser commonly works with for bitmask fields.
| Bit position | Power of two | Decimal value | Binary representation |
|---|---|---|---|
| 0 | 2^0 | 1 | 0b00000001 |
| 1 | 2^1 | 2 | 0b00000010 |
| 2 | 2^2 | 4 | 0b00000100 |
| 3 | 2^3 | 8 | 0b00001000 |
| 4 | 2^4 | 16 | 0b00010000 |
| 5 | 2^5 | 32 | 0b00100000 |
| 6 | 2^6 | 64 | 0b01000000 |
| 7 | 2^7 | 128 | 0b10000000 |
A bitmask value is the sum of the decimal values of every bit position that is set to 1. If bits 0, 2, and 3 are all set, the bitmask value is 1 + 4 + 8 = 13. If bits 1 and 5 are set, the bitmask value is 2 + 32 = 34. The arithmetic is simple addition; there is no carry between bit positions because each bit's contribution is a distinct power of two that does not overlap with any other bit's contribution.
Bitmask width limitations
The Unturned parser reads integer fields as signed thirty-two-bit integers in most contexts, which means up to thirty-one independent bit positions are available (bit 31 is reserved for the sign bit in signed integer representation and should not carry conditions in practice). In the weather ambience example from the official documentation, only the lowest two bits are used (bit 0 for rain and bit 1 for snow), but the same principle extends to any bit position up to bit 30.
The practical limit for bitmask fields in Unturned configuration is determined by the asset type's parser implementation, not by the integer width. The weather ambience volume uses a bitmask with two defined bits; other asset types may use wider bitmasks. The general rule is that a bitmask field value can be any non-negative integer up to 2,147,483,647 (the maximum value of a signed thirty-two-bit integer without setting the sign bit), and the parser will interpret each bit independently.
The weather ambience volume: canonical bitmask example
The official Smartly Dressed Games documentation provides one explicit bitmask example: the weather ambience volume. In this system, a volume in the game world can be configured to enable rain, snow, both, or neither. The configuration uses a bitmask field where bit 0 controls rain and bit 1 controls snow.
Bit assignment in the weather system
| Bit position | Decimal value | Weather condition | Mask name |
|---|---|---|---|
| 0 | 1 | Rain enabled | Rain |
| 1 | 2 | Snow enabled | Snow |
When the ambience volume's bitmask field is set to 1, rain is enabled and snow is disabled. When set to 2, snow is enabled and rain is disabled. When set to 3 (1 + 2), both rain and snow are enabled simultaneously. When set to 0, neither weather condition is active.
The official documentation expresses these values in binary notation for clarity:
| Configuration | Integer value | Binary notation | Meaning |
|---|---|---|---|
| No weather | 0 | 0b00 | Neither rain nor snow are enabled |
| Rain only | 1 | 0b01 | Rain is enabled; snow is disabled |
| Snow only | 2 | 0b10 | Snow is enabled; rain is disabled |
| Rain and snow | 3 | 0b11 | Both rain and snow are enabled |
The 0b prefix in the binary notation column is a convention for expressing binary literals in documentation. The parser itself accepts decimal integer values, not binary literal notation. A mod developer writing 0b11 in a .dat file would produce a parser error; the value must be written as 3.
How the parser reads the weather bitmask
When the Unturned engine loads an ambience volume that has a bitmask field set to 3, the following sequence occurs:
The sequence above shows the two-step decomposition that the engine performs at load time. The parser reads the integer value 3 from the .dat file. The ambience volume system then tests each bit position independently using a bitwise AND operation: value & bit_mask. If the result of the AND operation is non-zero, the corresponding condition is enabled. This test is performed once per defined bit position, at load time only.
Worked example: enabling rain only
To enable rain without enabling snow, the mod developer sets the bitmask field to 1. The binary representation is 0b01. The engine tests bit 0 (rain): 1 & 1 = 1, non-zero, rain is enabled. The engine tests bit 1 (snow): 1 & 2 = 0, zero, snow is disabled. The ambience volume produces rain with no snow.
Worked example: enabling both rain and snow
To enable both rain and snow, the mod developer sets the bitmask field to 3. The binary representation is 0b11. The engine tests bit 0: 3 & 1 = 1, non-zero, rain enabled. The engine tests bit 1: 3 & 2 = 2, non-zero, snow enabled. The ambience volume produces both effects simultaneously.
Rain's mask: 1 (binary 0b01)
Snow's mask: 2 (binary 0b10)
Rain + Snow: 3 (binary 0b11, 1 + 2)Integer versus hexadecimal representation
The Unturned parser accepts bitmask values in integer (decimal) format. Some .dat files in the vanilla asset set and community mod conventions occasionally use hexadecimal notation for bitmask fields, particularly when the bitmask is wide and individual bit positions are easier to identify in hexadecimal.
Hexadecimal (base-16) represents each group of four bits as a single character. The digits 0 through 9 represent values zero through nine, and the letters A through F (or a through f) represent values ten through fifteen.
| Binary (4 bits) | Decimal | Hexadecimal |
|---|---|---|
0000 | 0 | 0x0 |
0001 | 1 | 0x1 |
0010 | 2 | 0x2 |
0011 | 3 | 0x3 |
0100 | 4 | 0x4 |
0101 | 5 | 0x5 |
0110 | 6 | 0x6 |
0111 | 7 | 0x7 |
1000 | 8 | 0x8 |
1001 | 9 | 0x9 |
1010 | 10 | 0xA |
1011 | 11 | 0xB |
1100 | 12 | 0xC |
1101 | 13 | 0xD |
1110 | 14 | 0xE |
1111 | 15 | 0xF |
For a bitmask value with several high bits set, hexadecimal is more compact and easier to read at a glance. For example, a bitmask with bits 0, 3, 5, and 7 set has a decimal value of 1 + 8 + 32 + 128 = 169. In hexadecimal, the same value is 0xA9, and in binary it is 0b10101001. The hexadecimal representation groups the bits into two four-bit nibbles: 1010 (A) and 1001 (9). The grouping makes it straightforward to identify which bits are set by reading the hexadecimal digits: A = 1010 has bits 3 and 1 set, 9 = 1001 has bits 3 and 0 set, so the combined byte has bits 7, 5, 3, and 0 set.
Hexadecimal and the parser
The Unturned .dat parser is documented to accept integer values for bitmask fields. If a hexadecimal value is written in a .dat file, the parser's handling of the value depends on the specific parser implementation for that asset type. The cohort recommendation is to use decimal integer values for all bitmask fields unless the official documentation or a specific asset type's examples use hexadecimal, in which case match the documented convention.
Bitmask values as powers of two: the general case
In the weather example, the bitmask uses only two bit positions with values of 1 and 2. For a bitmask with more bits, the values follow the powers-of-two sequence: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, and so on up to 2^30 = 1,073,741,824. Each bit position doubles the value of the previous position.
The table below lists the first sixteen bit positions with their decimal values and the hexadecimal value that each bit contributes to the overall bitmask integer.
| Bit number | Decimal value | Hex value | Bit mask for testing (bitwise AND) |
|---|---|---|---|
| 0 | 1 | 0x1 | 0x1 |
| 1 | 2 | 0x2 | 0x2 |
| 2 | 4 | 0x4 | 0x4 |
| 3 | 8 | 0x8 | 0x8 |
| 4 | 16 | 0x10 | 0x10 |
| 5 | 32 | 0x20 | 0x20 |
| 6 | 64 | 0x40 | 0x40 |
| 7 | 128 | 0x80 | 0x80 |
| 8 | 256 | 0x100 | 0x100 |
| 9 | 512 | 0x200 | 0x200 |
| 10 | 1,024 | 0x400 | 0x400 |
| 11 | 2,048 | 0x800 | 0x800 |
| 12 | 4,096 | 0x1000 | 0x1000 |
| 13 | 8,192 | 0x2000 | 0x2000 |
| 14 | 16,384 | 0x4000 | 0x4000 |
| 15 | 32,768 | 0x8000 | 0x8000 |
A bitmask value is computed by adding together the decimal values of every bit position the mod developer wants to set. If the desired condition set is bits 2, 4, and 9, the bitmask value is 4 + 16 + 512 = 532. The arithmetic is checked by writing the binary: 0b001000010100 (bits 9, 4, and 2 set), which in hexadecimal is 0x214, which equals 2*256 + 1*16 + 4 = 512 + 16 + 4 = 532.
Relationship between bitmasks and enum flags
Bitmasks and enum flags are related but distinct concepts in the Unturned type system. An enum flag is a named constant that represents a specific bit position within a bitmask. The weather example uses two enum flags: the rain flag (1) and the snow flag (2). These are the enum values that the bitmask combines.
The bitmask is the container , the integer field that stores the combined value. The enum flags are the individual conditions that the bitmask encodes. A field documented as accepting a bitmask expects a value that is the sum of one or more enum flag values. A field documented as accepting an enum flag expects a single flag value (and using a sum would be an error in that context).
The documentation convention in the Smartly Dressed Games reference material is to list the enum flag values alongside the bitmask field, so the mod developer knows which bit position corresponds to which condition. The weather documentation lists the rain mask as 1 and the snow mask as 2, which is the complete definition of the enum flags for that bitmask.
The flowchart above shows the relationship between enum flags and the bitmask field. The enum flags define the possible conditions; the bitmask field stores which combination of conditions is active; the parser decomposes the bitmask back into the individual conditions at load time.
Writing bitmask values in .dat files
The syntax for writing a bitmask value in a .dat file is identical to writing any other integer field:
BitmaskField 3The integer 3 is the sum of the enum flag values for the conditions the mod developer wants to enable. There is no special syntax for bitmask fields , the parser knows from the field definition that the integer should be treated as a bitmask and decomposed accordingly.
Worked example: a hypothetical multi-condition bitmask
Consider a hypothetical bitmask field on a barricade asset that controls which interaction modes are enabled, where the enum flags are:
| Condition | Bit | Value |
|---|---|---|
| Interactable by players | 0 | 1 |
| Interactable by zombies | 1 | 2 |
| Emits light | 2 | 4 |
| Emits sound | 3 | 8 |
| Affected by gravity | 4 | 16 |
| Immune to explosion damage | 5 | 32 |
To configure a barricade that is interactable by players, emits light, and is immune to explosion damage, the bitmask value is 1 + 4 + 32 = 37. To configure a barricade that is interactable by players, interactable by zombies, emits sound, and is affected by gravity, the bitmask value is 1 + 2 + 8 + 16 = 27. The .dat file entry for the first case is:
InteractionMask 37The parser decomposes 37 into binary 0b100101 and activates the conditions corresponding to bits 0, 2, and 5. The conditions corresponding to bits 1, 3, and 4 are disabled.
Common authoring mistake: writing binary literal notation
A mod developer who reads the official documentation and sees the binary notation 0b01 for rain and 0b10 for snow may attempt to write the binary literal directly in the .dat file:
WeatherMask 0b11The parser expects an integer value and does not interpret the 0b prefix as a binary literal marker. The value 0b11 is not a valid integer and will produce a parser error. The correct entry is the decimal integer:
WeatherMask 3Binary literal notation is documentation-only
The 0b prefix notation used in the official Smartly Dressed Games documentation is a convention for expressing binary values in human-readable form. It is not accepted by the .dat file parser. Always convert binary notation to the corresponding decimal integer before writing the value into a .dat file.
Reading bitmask values: the bitwise AND test
To determine whether a specific bit is set in a bitmask value, the standard programming technique is the bitwise AND operation. Given a bitmask value V and a bit position's value M (the mask, which is 2^bit_number), the test V & M evaluates to M if the bit is set, and 0 if the bit is not set.
For the weather example with V = 3:
| Test | Expression | Result | Interpretation |
|---|---|---|---|
| Is rain enabled? | 3 & 1 | 1 (non-zero) | Rain is enabled |
| Is snow enabled? | 3 & 2 | 2 (non-zero) | Snow is enabled |
| Is hypothetical bit 2 condition enabled? | 3 & 4 | 0 (zero) | Not enabled |
The bitwise AND test is the operation the engine performs internally to determine which conditions are active from a bitmask field. Mod developers who are reading bitmask values from configuration files or who are working with server-side scripting that exposes bitmask fields as integers should use the same bitwise AND test to check individual conditions.
The flowchart above describes the standard bitmask decomposition algorithm. The engine runs this algorithm once per bitmask field at load time. Server-side scripts that read bitmask fields from configuration at runtime may run the equivalent check on demand.
Composing bitmask values: the bitwise OR combination
To combine multiple enum flag values into a single bitmask value, the standard programming technique is the bitwise OR operation. Given two flag values A and B, the combined bitmask is A | B.
For the weather example: 1 | 2 = 3. The bitwise OR of rain's mask (1, binary 0b01) and snow's mask (2, binary 0b10) produces the combined mask (3, binary 0b11).
For the hypothetical barricade example, to combine interactable-by-players (1), emits-light (4), and immune-to-explosion (32): 1 | 4 | 32 = 37. The bitwise OR is commutative and associative: (1 | 4) | 32 produces the same result as 1 | (4 | 32).
Mod developers who are composing bitmask values programmatically (in server-side plugins, build scripts, or mod authoring tools) should use bitwise OR to combine flag values. Mod developers who are composing bitmask values by hand for .dat files should simply add the flag values together , addition and bitwise OR produce the same result when the flag values are distinct powers of two, because there is no carry between bit positions for values that do not share any bits.
Removing a condition from a bitmask: the bitwise AND NOT operation
To remove a specific condition from a bitmask value while leaving all other conditions intact, the standard programming technique is the bitwise AND NOT operation. Given a bitmask value V and a flag value F, the new value is V & ~F.
For the weather example, to remove snow from a combined rain-and-snow bitmask of 3: 3 & ~2 = 3 & (bitwise NOT of 2) = 3 & 0xFFFFFFFD = 1. The resulting value is 1, which is the rain-only bitmask. Rain was enabled before the operation and remains enabled; snow was enabled before the operation and is now disabled.
In .dat file authoring, removing a condition from a bitmask is done by recomputing the sum of the desired flags and writing the new value. There is no syntax for "subtract this condition from the bitmask" in the .dat format; the value is always the full sum of all desired flags.
How bitmasks differ from enum (single-value) fields
A field documented as an enum type expects exactly one named value. A field documented as a bitmask type expects the sum of zero or more named flag values. The difference is in how the parser interprets the integer.
| Type | Accepts | Example value | Meaning |
|---|---|---|---|
| Enum (single-value) | One named constant | Rain | The field's value is the single constant Rain |
| Bitmask | Sum of zero or more named flags | 3 | The field encodes both the Rain flag and the Snow flag |
Writing a sum of enum flags where a single enum value is expected will produce a parser error or unexpected behavior, because the parser will compare the integer against the list of known values and find no match. Writing a single enum flag where a bitmask is expected will work correctly , a single flag is a valid bitmask with only one bit set , and will enable only that one condition.
Enum versus bitmask: reading the documentation
When the official documentation lists multiple numeric values for a field and describes them as masks (e.g., "Rain's default mask is 1, and snow's default mask is 2"), the field is a bitmask type. When the documentation lists named values and does not mention masks, the field is an enum type. The word "mask" in the documentation is the signal that bitwise combination is expected.
How bitmasks differ from flag types
A flag type is a key whose presence in the .dat file indicates a true condition, with no associated value. A flag cannot carry multiple conditions in a single line; each condition requires its own flag key. A bitmask encodes multiple conditions in a single integer value on a single line.
| Type | Encoding | Conditions per line | Example |
|---|---|---|---|
| Flag | Presence-only key | One condition per key | Pro |
| Bitmask | Integer sum of flag values | Multiple conditions per integer | WeatherMask 3 |
A mod developer configuring a system with many independent binary conditions must weigh the trade-off between a multi-line flag approach (each condition on its own line, each condition clearly labeled) and a single-line bitmask approach (all conditions encoded in one integer, less verbose but requiring the developer to compute the sum). The Unturned engine uses bitmasks where the set of conditions can be combined arbitrarily (the weather system) and flags where the conditions are independent but typically accessed one at a time by the runtime (the Pro, Hair, and Beard flags on item assets).
The bitmask type is more compact for storing combinations; the flag type is clearer for listing individual properties. Neither is a substitute for the other; the parser expects the type documented for each field and will misinterpret a flag where a bitmask integer is expected, or vice versa.
Diagnostic table: common bitmask errors
| Symptom | Most likely cause | Resolution |
|---|---|---|
| Parser error on bitmask field | Value written in binary literal notation (0b11) instead of decimal integer (3) | Convert the binary literal to the decimal integer value |
| Bitmask field accepted but condition not active in-game | The bit position for that condition was not included in the sum | Recompute the bitmask value to include the desired bit's decimal value |
| Too many conditions active | Bitmask value includes bit positions for unintended conditions | Recompute the bitmask value, excluding the unintended bit positions |
| Condition that should be independent toggles is controlled by a single enum | The field is documented as an enum type, not a bitmask type | Use the field as documented; combination is not supported |
| Adding a new condition to an existing bitmask in a later version breaks existing configs | New condition assigned to a bit position already in use by another condition | Assign new conditions to unused bit positions; document the bit positions |
| Bitmask value is negative in a server-side script | The sign bit (bit 31) is being used as a condition bit in a signed integer context | Use only bits 0-30 for condition storage; bit 31 is the sign bit |
Hex value 0xA written in .dat file not recognized | The parser may not accept hex prefix notation for this field | Use the decimal integer 10 instead of 0xA |
Worked examples: building bitmask values by hand
The worked examples below demonstrate the manual process for composing bitmask values. Each example lists the desired conditions, the bit positions and decimal values of those conditions, and the final bitmask value.
Example 1: single condition
Desired condition: bit 3 only.
Bit 3 has a decimal value of 8. The bitmask value is 8. The .dat file entry is:
BitmaskField 8Example 2: two non-adjacent conditions
Desired conditions: bit 0 and bit 5.
Bit 0 has a decimal value of 1. Bit 5 has a decimal value of 32. The bitmask value is 1 + 32 = 33. The .dat file entry is:
BitmaskField 33Example 3: contiguous block of conditions
Desired conditions: bits 0, 1, 2, and 3.
Bit 0 = 1, bit 1 = 2, bit 2 = 4, bit 3 = 8. Sum: 1 + 2 + 4 + 8 = 15. The .dat file entry is:
BitmaskField 15Note that 15 is one less than 16, which is the value of bit 4. The sum of a contiguous block of bits starting from bit 0 is always 2^n - 1, where n is the number of bits. Bits 0 through 3 is four bits, so the sum is 2^4 - 1 = 16 - 1 = 15. This shortcut is useful for quick mental arithmetic when composing contiguous-block bitmasks.
Example 4: every condition in a wide bitmask
Desired conditions: bits 0 through 9, inclusive.
Using the contiguous-block shortcut: ten bits, so the sum is 2^10 - 1 = 1024 - 1 = 1023. The .dat file entry is:
BitmaskField 1023Example 5: zero conditions (all disabled)
Desired conditions: none.
The bitmask value is 0. The .dat file entry is:
BitmaskField 0A bitmask value of 0 disables all conditions and is the default value when the field is not specified and the engine uses its default.
Working with bitmasks in server-side scripting
Server-side plugins written for the Unturned Dedicated Server API or the OpenMod framework may encounter bitmask values as integer fields on asset objects. The standard C# bitwise operators apply directly:
| Operation | C# expression | Purpose |
|---|---|---|
| Test if bit is set | (value & mask) != 0 | Check whether a specific condition is active |
| Set a bit | `value | = mask` |
| Clear a bit | value &= ~mask | Disable a condition without affecting others |
| Toggle a bit | value ^= mask | Flip a condition from on to off or off to on |
| Test if multiple bits are all set | (value & combinedMask) == combinedMask | Check whether all conditions in a set are active |
| Test if any of multiple bits are set | (value & combinedMask) != 0 | Check whether any condition in a set is active |
The mask value mask in each expression is the decimal value of the bit position (e.g., 1, 2, 4, 8, ...). The combined mask combinedMask is the bitwise OR of multiple mask values (e.g., 1 | 4 = 5 if bits 0 and 2 form the set).
Bitmask constants in C# plugins
Define bitmask flag values as named constants using bit-shift notation for clarity. The constant 1 << 0 equals 1 (bit 0), 1 << 1 equals 2 (bit 1), 1 << 2 equals 4 (bit 2), and so on. Named constants make the bitmask logic self-documenting: (value & ConditionRain) != 0 is clearer than (value & 1) != 0 when the script is read six months later.
Bitmask layout design: assigning bit positions for custom configuration
When designing a custom configuration bitmask for a server-side plugin or a mod that introduces new bitmask fields, the bit position assignment should follow several documented conventions to avoid the most common maintenance problems.
| Convention | Rationale |
|---|---|
| Assign bit 0 first, then proceed upward | Bit 0 is the least significant bit and is always available |
| Document each bit position with its decimal value | Prevents confusion about which value corresponds to which condition |
| Reserve unused bit positions for future conditions | Adding a new condition in a later version does not shift existing bit positions |
| Do not assign the sign bit (bit 31) as a condition | The sign bit changes the integer's sign in signed integer contexts |
| Group related conditions in contiguous bit ranges | Makes the hexadecimal representation readable as groups |
| Use the powers-of-two sequence consistently | Avoids overlap between bit positions |
The bit position assignment table for a custom configuration bitmask should be included in the mod's documentation, following the same format as the weather ambience table in this article.
Appendix A: Powers of two reference table (bits 0 through 31)
The table below lists every bit position from 0 through 31 with its decimal value, for quick reference when composing bitmask values. The values are listed in decimal and hexadecimal formats.
| Bit | Decimal | Hexadecimal |
|---|---|---|
| 0 | 1 | 0x1 |
| 1 | 2 | 0x2 |
| 2 | 4 | 0x4 |
| 3 | 8 | 0x8 |
| 4 | 16 | 0x10 |
| 5 | 32 | 0x20 |
| 6 | 64 | 0x40 |
| 7 | 128 | 0x80 |
| 8 | 256 | 0x100 |
| 9 | 512 | 0x200 |
| 10 | 1,024 | 0x400 |
| 11 | 2,048 | 0x800 |
| 12 | 4,096 | 0x1000 |
| 13 | 8,192 | 0x2000 |
| 14 | 16,384 | 0x4000 |
| 15 | 32,768 | 0x8000 |
| 16 | 65,536 | 0x10000 |
| 17 | 131,072 | 0x20000 |
| 18 | 262,144 | 0x40000 |
| 19 | 524,288 | 0x80000 |
| 20 | 1,048,576 | 0x100000 |
| 21 | 2,097,152 | 0x200000 |
| 22 | 4,194,304 | 0x400000 |
| 23 | 8,388,608 | 0x800000 |
| 24 | 16,777,216 | 0x1000000 |
| 25 | 33,554,432 | 0x2000000 |
| 26 | 67,108,864 | 0x4000000 |
| 27 | 134,217,728 | 0x8000000 |
| 28 | 268,435,456 | 0x10000000 |
| 29 | 536,870,912 | 0x20000000 |
| 30 | 1,073,741,824 | 0x40000000 |
| 31 | 2,147,483,648 | 0x80000000 (sign bit, not for condition use) |
Appendix B: Quick-reference bitmask composition worksheet
The worksheet below is a template for manually composing bitmask values. A mod developer copies the template into a text file, fills in the desired bit positions, and computes the sum.
Bitmask Field: _______________________
Enum flag definitions:
| Condition name | Bit position | Decimal value |
|---|---|---|
| ________________ | ___ | ______ |
| ________________ | ___ | ______ |
| ________________ | ___ | ______ |
| ________________ | ___ | ______ |
| ________________ | ___ | ______ |
| ________________ | ___ | ______ |
Desired active conditions:
- ________________ (bit ___, value ______)
- ________________ (bit ___, value ______)
- ________________ (bit ___, value ______)
Sum of values: ______ + ______ + ______ = ______
.dat file entry:
BitmaskField ______Appendix C: External references
| Resource | URL | Notes |
|---|---|---|
| Smartly Dressed Games modding documentation | https://docs.smartlydressedgames.com/en/stable/ | Official field reference; includes the bitmask chapter and the weather ambience volume example |
| Unturned on Steam | https://store.steampowered.com/app/304930/Unturned/ | Game page; changelog notes may reference bitmask configuration changes |
Frequently asked questions
What is a bitmask?
A bitmask is an integer value where each bit position represents an independent on/off condition. A bitmask with bits 0 and 1 set has a value of 3. A bitmask with bit 2 set has a value of 4. The integer is the sum of the decimal values of every bit position that is set to 1.
How do I know whether a field is a bitmask or an enum?
When the official documentation describes a field's values as masks and lists numeric mask values for each named condition (e.g., "Rain's default mask is 1"), the field is a bitmask type. When the documentation lists named values without referencing masks, the field is an enum type. The word "mask" in the documentation is the signal.
Can I write hexadecimal values for bitmask fields in .dat files?
The .dat parser is documented to accept integer values for bitmask fields. Some asset types may accept hexadecimal notation with a 0x prefix; others may not. The cohort recommendation is to use decimal integer values for all bitmask fields unless the official documentation or the vanilla asset examples for that specific field use hexadecimal notation, in which case match the documented convention.
Why does 0b11 produce a parser error in my .dat file?
The 0b prefix notation is a documentation convention for expressing binary literals in human-readable form. The .dat parser expects integer values and does not interpret the 0b prefix as a binary literal marker. Write the decimal integer 3 instead of 0b11.
How do I enable two conditions in a bitmask field?
Add together the decimal values of the two conditions' bit positions. If condition A is bit 0 (value 1) and condition B is bit 2 (value 4), the combined bitmask value is 1 + 4 = 5. Write 5 in the .dat file.
How do I enable all conditions in a bitmask field?
Add together the decimal values of every defined bit position. If the defined conditions occupy bits 0 through 3, the combined value is 1 + 2 + 4 + 8 = 15. For a contiguous block of conditions starting at bit 0, the value is 2^n - 1 where n is the number of bits.
How do I disable all conditions in a bitmask field?
Set the bitmask field to 0. A value of 0 means no bits are set, which disables every condition.
What is the difference between a bitmask and a flag?
A bitmask is a single integer field that encodes multiple independent conditions. A flag is a key whose presence in the file indicates a single condition. A bitmask field with three conditions enabled is one line of configuration; three flag conditions require three separate lines. The bitmask is more compact; the flag is clearer for listing individual properties.
Can a bitmask value be negative?
The signed thirty-two-bit integer used by the Unturned parser can hold negative values if bit 31 (the sign bit) is set. Bit 31 should not be used for condition storage in signed integer contexts because setting it changes the integer's sign and may produce unexpected parser behavior. Use only bits 0 through 30 for condition storage.
How do I test a bitmask value in a server-side script?
Use the bitwise AND operator: (value & mask) != 0. If value is the bitmask integer and mask is the decimal value of the bit position you want to test, the expression is non-zero when the condition is enabled and zero when the condition is disabled. For example, (weatherMask & 1) != 0 tests whether rain is enabled in the weather bitmask.
How many conditions can a single bitmask field encode?
Up to thirty-one independent conditions (bits 0 through 30) in a signed thirty-two-bit integer context. Bit 31 is the sign bit and should not carry condition data. If the parser for a specific asset type uses an unsigned integer, the full thirty-two bits are available, but this is not the documented convention in the Unturned .dat parser.
How do I add a new condition to an existing mod's bitmask field in a later version?
Assign the new condition to the next unused bit position. Existing bit positions must remain unchanged so that existing configurations continue to work. Document the new bit position and its decimal value in the mod's changelog. If the existing bitmask field has conditions on bits 0 and 1, assign the new condition to bit 2 (value 4).
Is there a maximum value for a bitmask field in a .dat file?
The practical maximum for a signed thirty-two-bit integer is 2,147,483,647 (bits 0 through 30 all set). The absolute maximum for a signed thirty-two-bit integer is 2,147,483,647; values larger than this set the sign bit and become negative, which the parser may not handle as a valid bitmask.
Best practices
- Always write bitmask values as decimal integers in
.datfiles, not as binary literal notation - Use the powers-of-two reference table when composing bitmask values by hand
- Document every bit position with its condition name and decimal value in the mod's reference documentation
- Reserve unused bit positions in a custom bitmask field for future conditions
- Do not assign the sign bit (bit 31) as a condition in signed integer contexts
- Test each bit independently at load time in server-side scripts
- Use named constants for bitmask flag values in C# server-side plugins
- When adding conditions to a bitmask field in a later mod version, assign to unused bit positions only
- Convert documentation binary notation to decimal before writing into any
.datfile - Verify the bitmask behavior in single-player by testing with a known value before distributing the mod
Appendix D: Bitmask diagnostic flowchart
The flowchart below addresses the most common bitmask-related problems that mod developers encounter when authoring .dat files.
The flowchart is the recommended triage entry point. The diagnostic table earlier in this article provides the detailed resolution for each branch.
Document history
| Version | Date | Author | Notes |
|---|---|---|---|
| 1.0 | 2026-07-26 | 57 Studios | Initial publication. Bitmask type reference with binary arithmetic, weather ambience example, decimal/hex/binary formats, bitwise operations, diagnostic table, and powers-of-two reference. |
Cross-references
- Master Bundle Pointer Type Reference , the previous article in this section; covers the master bundle pointer data type.
- Flag Type Reference , the next article; covers the flag data type that is a companion to the bitmask type.
- Smartly Dressed Games modding documentation , official field reference; includes the bitmask chapter.
- Unturned on Steam , game and community hub.