item#

The item block is used to create items in the game, from weapons to food and clothing. The parameters available in this block mostly depend on the type of item you are creating, set with ItemType.

To get started, create a simple item structure by setting that parameter up correctly, then add more parameters as you need. For example, for a normal item:

module yourModule
{
  item yourID
  {
    ItemType = base:normal,
    ...
  }
}

To add a name to display for your item, you need to add the item full type, that is its module.id, inside the ItemName translation file. Taking the example from above, your translation file would be:

{
  "yourModule.yourID": "Your Item Name"
}

This block can be soft overridden in scripts.

Hierarchy#

Valid Parent Blocks:

Possible Child Blocks:

ID Properties#

This block should have an ID.

Parameters#

AcceptItemFunction#

Type:

Any

No description

AcceptMediaType#

Type:

integer

Default:

-1

No description

ActivatedItem#

Type:

Any

No description

AimingMod#

Type:

Any

No description

AimingPerkCritModifier#

Type:

integer

See CriticalChance for more details.

AimingPerkHitChanceModifier#

Type:

float

See HitChance for more details.

AimingPerkMinAngleModifier#

Type:

float

Needs:

ItemType = base:weapon

See MinAngle for more details.

AimingPerkRangeModifier#

Type:

float

Needs:

ItemType = base:weapon

See MaxRange for more details.

Aimingtime#

Type:

integer

Needs:

ItemType = base:weapon

Aimingtime is a stat which is directly applied to a HandWeapon while AimingTimeModifier is applied to weapon parts. The attachments directly add or subtract their AimingTimeModifier to the aiming delay.

It controls the aim-settling delay, the aiming delay counter that must tick down to 0 before the weapon is “settled”. Lower values means faster target reacquisition after each shots. The primary “how snappy does this gun feel” lever for semi-automatic guns. It tick down the aiming via the following formula:

rate = 0.625 x gameSpeed x (1 + 0.05 x AimingLevel + (Marksman ? 0.1 : 0))

The marksman trait being no longer accessible in the recent versions of the game, the condition involving it will never be reached.

Note: This formula might not be fully accurate as time deltas don’t appear in the formula.

While aimingDelay > 0, both hit chance and critical chance take an aim-delay penalty proportional to the remaining delay. The countdown only starts after recoilDelay has recovered, so high RecoilDelay directly delays when AimingTime begins ticking.

On each shots or equip, the aiming delay will be increased or reduced, being impacted by aiming while in a vehicle, being reduced by the trait Dextrous or increased by All Thumbs. The following formula is used:

aimingDelay = AimingTime
        * (Dextrous ? 0.8 : AllThumbs ? 1.2 : 1.0)
        * (in vehicle ? 1.5 : 1.0)

AimingTimeModifier#

Type:

integer

Needs:

ItemType = base:weaponpart

See Aimingtime for more details.

AimReleaseSound#

Type:

Any

No description

AlarmSound#

Type:

Any

No description

Alcoholic#

Type:

Any

No description

AlcoholPower#

Type:

Any

No description

AlwaysKnockdown#

Type:

Any

No description

AlwaysWelcomeGift#

Type:

Any

No description

AmmoBox#

Type:

string (block: item, with module)

Needs:

ItemType = base:weapon; IsAimedFirearm = True

No description

AmmoType#

Type:

string

Needs:

ItemType = base:weapon, base:normal

AmmoType indicates what ammo is consumed when shooting, but it also determines tracer and hit-reaction sound lookups. The value needs to reference the registries entry of the ammo you want to use. The vanilla ammunition types which are available by default are:

  • base:bullets_3030

  • base:bullets_308

  • base:bullets_357

  • base:bullets_38

  • base:bullets_44

  • base:bullets_45

  • base:bullets_556

  • base:bullets_9mm

  • base:cap_gun_cap

  • base:shotgun_shells

AmmoBox is used to indicate the type of ammo box associated to the weapon. This is mostly used to spawn this type of ammo box alongside the gun.

MagazineType is used to set the magazine item the gun uses. If not provided, then the gun doesn’t use a magazine item and loads rounds individually. MaxAmmo is used to set the capacity of either the magazine item or the gun.

WeaponReloadType is used to select the reload workflow of the gun. Notably affects rack-after-shot, insertion style and animations. The provided value references the variable condition WeaponReloadType in AnimNodes. The game has the following values available by default:

  • handgun

  • shotgun

  • boltactionnomag

  • boltaction

  • revolver

  • doublebarrelshotgun

  • doublebarrelshotgunsawn

A custom WeaponReloadType can be used if the relevant animations and condition logic are properly set up in a custom AnimNode.

AngleFalloff#

Type:

Any

No description

AnimalFeedType#

Type:

Any

No description

AttachmentReplacement#

Type:

Any

No description

AttachmentsProvided#

Type:

Any

No description

AttachmentType#

Type:

Any

No description

BadCold#

Type:

Any

No description

BadInMicrowave#

Type:

Any

Used to set whether this item will cause a fire when put in a microwave.

BandagePower#

Type:

Any

No description

BaseSpeed#

Type:

float

Default:

1.0

No description

BaseVolumeRange#

Type:

Any

No description

BiteDefense#

Type:

Any

No description

BloodLocation#

Type:

array (array of string, separator: ‘;’)

No description

Allowed values:

  • Apron

  • ShirtNoSleeves

  • JumperNoSleeves

  • Shirt

  • ShirtLongSleeves

  • Jumper

  • Jacket

  • LongJacket

  • ShortsShort

  • Trousers

  • Shoes

  • FullHelmet

  • Bag

  • Hands

  • Head

  • Neck

  • Groin

  • UpperBody

  • LowerBody

  • LowerLegs

  • UpperLegs

  • LowerArms

  • UpperArms

  • Hand_L

  • Hand_R

  • ForeArm_L

  • ForeArm_R

  • UpperArm_L

  • UpperArm_R

  • UpperLeg_L

  • UpperLeg_R

  • LowerLeg_L

  • LowerLeg_R

  • Foot_L

  • Foot_R

BodyLocation#

Type:

Any

Used to define which location on the human character this clothing item can be worn.

book_subject#

Type:

Any

No description

BoredomChange#

Type:

Any

No description

brakeForce#

Type:

Any

No description

BreakSound#

Type:

string (block: sound)

No description

BringToBearSound#

Type:

string (block: sound)

No description

BulletDefense#

Type:

Any

No description

BulletHitArmourSound#

Type:

Any

No description

Calories#

Type:

Any

No description

CanAttach#

Type:

Any

No description

CanBandage#

Type:

Any

No description

CanBarricade#

Type:

Any

No description

CanBeEquipped#

Type:

Any

No description

CanBePlaced#

Type:

Any

No description

CanBeRemote#

Type:

Any

No description

CanBeReused#

Type:

Any

No description

CanBeWrite#

Type:

Any

No description

CanDetach#

Type:

Any

No description

CanHaveHoles#

Type:

boolean

Default:

True

Used to define whenever this item can get holes in it.

CannedFood#

Type:

Any

No description

CanStack#

Type:

Any

No description

CanStoreWater#

Type:

Any

No description

CantAttackWithLowestEndurance#

Type:

Any

No description

cantBeConsolided#

Type:

Any

No description

CantBeFrozen#

Type:

Any

No description

CantEat#

Type:

Any

No description

Capacity#

Type:

integer

Default:

-1

No description

Carbohydrates#

Type:

Any

No description

Categories#

Type:

Any

No description

ChanceToFall#

Type:

Any

No description

ChanceToSpawnDamaged#

Type:

Any

No description

ClickSound#

Type:

string (block: sound)

Default:

Stormy9mmClick

Needs:

ItemType = base:weapon

No description

ClipSize#

Type:

Any

No description

CloseKillMove#

Type:

Any

Used to whenever this weapon can be used to do a close kill move, like knives to assassinate in the back.

CloseSound#

Type:

Any

No description

ClothingExtraSubmenu#

Type:

Any

See ClothingItem for more details.

ClothingItem#

Type:

Any

ClothingItem references the clothing defined inside the clothing.xml file. ClothingExtraSubmenu will define the name of the context menu option to equip the clothing item.

ClothingItemExtra and ClothingItemExtraOption are used to define additional clothing equip options, they reference another item script block.

ClothingItemExtra#

Type:

Any

Needs:

ClothingItemExtraOption

See ClothingItem for more details.

ClothingItemExtraOption#

Type:

Any

Needs:

ClothingItemExtra

See ClothingItem for more details.

ColorBlue#

Type:

integer

Default:

255

No description

ColorGreen#

Type:

integer

Default:

255

No description

ColorRed#

Type:

integer

Default:

255

No description

CombatSpeedModifier#

Type:

float

Default:

1.0

No description

ConditionAffectsCapacity#

Type:

Any

Set whenever condition of the item can impact the capacity value of the container.

ConditionLowerChanceOneIn#

Type:

integer

Default:

10

ConditionLowerChanceOneIn impacts the durability of the item, reducing the value used to calculate the chance by doing chance = 1/ConditionLowerChanceOneIn, which means increasing this parameter value will reduce the chance to damage the item.

ConditionMax sets the total durability pool, starting condition and repair ceiling. Make these two parameters high for robust military rifles, and low for a cheap civilian gun.

ConditionLowerOffroad#

Type:

Any

No description

ConditionLowerStandard#

Type:

Any

No description

ConditionMax#

Type:

integer

Default:

10

No description

ConsolidateOption#

Type:

Any

No description

CookingSound#

Type:

string (block: sound)

Custom sound to play when cooking this item.

CorpseSicknessDefense#

Type:

Any

No description

Cosmetic#

Type:

Any

No description

Count#

Type:

integer

Default:

1

The parameter is unused in the game scripts, unclear what it is used for.

CritDmgMultiplier#

Type:

float

Default:

2.0

Multiplier applied to the damage of a hit if it is a critical hit, applied inside IsoGameCharacter.Hit()). Two types of crits can trigger:

  • A normal crit: damage *= max(2.0, CritDmgMultiplier)

  • Aim-at-floor stomp (melee only): damage *= max(5.0, CritDmgMultiplier)

The default value of the HandWeapon class is 2.0. Values of 3.0 to 5.0 visibly spike crit damage while values above 5.0 also start boosting stomps.

CriticalChance#

Type:

float

Default:

20.0

Needs:

ItemType = base:weapon

CriticalChance sets the base critical hit chance of the weapon. The final CriticalChance value after all applied bonuses and penalties have been applied is compared on a 0-100 roll.

Below is a table listing the different elements which can influence the critical hit chance of a weapon:

Element

Type

Description

Formula

AimingPerkCritModifier and aiming skill of the character

Weapon parameter

The aiming level of the character impacts the player’s critical hit chance by adding the following to the CriticalChance value.

CriticalChance += AimingPerkCritModifier * Aiming level

Sight bonus / penalty

Weapon parameter

In the formula, sightWindowBonus refers to the bonus from MinSightRange and MaxSightRange. sightlessBonus on the other hand is a simpler parameter which uses a distance falloff when there is not active sight. The best path is used for the better result. The aim delay penalty depends on Aimingtime

CriticalChance += max(sightlessBonus - sightlessAimDelayPenalty, sightWindowBonus - sightWindowAimDelayPenalty)

Moodles penalty

Player condition

Being panicked, stressed, tired, drunk or lacking endurance will all negatively impact the CriticalChance.

CriticalChance -= moodlesPenalty

Weather penalty

Environment

Wind, rain, fog, low-light will all negatively impact the CriticalChance.

CriticalChance -= weatherPenalty

Movement penalty

Player condition

The shooter speed and the distance will negatively impact the CriticalChance.

CriticalChance -= movementPenalty

Marksman trait

Player condition

This condition can never be reached as the Marksman trait no longer exists.

CriticalChance += 10

For PvP targets, the entire formula is bypassed and StopPower is used instead. StopPower is never used against non-player targets.

CriticalChance = StopPower * ( 1 + Aiming level / 15)

CriticalChance sets the floor for unskilled players while AimingPerkCritModifier rewards more or less the character ability to aim. High modified and low base chance means the weapon is a skill-gated crit machine, making the weapon a sort of “experts” weapon.

CustomContextMenu#

Type:

Any

No description

CustomEatSound#

Type:

Any

Attributes:

Can be empty

Custom sound to play when eating or drinking this item, refers to the ID of a sound script. Set to an empty string to disable any sound from playing.

CyclicRateMultiplier#

Type:

float

Range:

Min: 0.0

Default:

1.0

Needs:

ItemType = base:weapon; IsAimedFirearm = True

Only in Auto fire mode. Drives the full-auto animation cycle rate via the autoShootSpeed animation variable.

A higher value means more shots per second. In Single mode this field is ignored and shot speed comes from RecoilDelay and Aimingtime instead.

Increase for SMG feel and decrease for heavy LMG feel.

DamageCategory#

Type:

Any

No description

DamageMakeHole#

Type:

Any

No description

DangerousUncooked#

Type:

boolean

Needs:

ItemType = base:food

If true, the item will cause food poisoning when eaten raw. Used for example for raw meat. The iron gut trait will stop you from getting sick from eating a raw food with the tag Egg. The severity of the food poisoning is not impacted by traits or other criteria, only by the quantity of food you eat.

DaysFresh#

Type:

integer

Default:

1000000000

Needs:

ItemType = base:food

DaysFresh sets how many days this food item will stay fresh with default sandbox settings. DaysTotallyRotten sets how many days this food item will take to rot.

Icon provides the ability to set a different icon for the rotten and stale version of the food.

DaysTotallyRotten#

Type:

integer

Default:

1000000000

Needs:

ItemType = base:food

See DaysFresh for more details.

DigitalPadlock#

Type:

Any

No description

DigType#

Type:

Any

No description

DisappearOnUse#

Type:

boolean

Default:

True

No description

DiscomfortModifier#

Type:

Any

No description

DisplayCategory#

Type:

Any

No description

DisplayName#

Type:

Any

Sets the name of the item which will be displayed in-game. It’s recommended to use a translation entry for this parameter to allow localization of the item name.

Warning

Deprecated (since version 42.13.0)

Naming an item should be done with a translation entry. See the wiki page for more information.

DoorDamage#

Type:

integer

Range:

Min: 1

Default:

1

Damage dealt to doors, windows, barricades and some vehicle/object hits. The damage to doors cannot go lower than 1, even in the formulas it is clamped to a minimum of 1. The formula used to retrieve the damage to doors is:

damage = max(1, DoorDamage * sharpness multiplier)

More parameters will impact the door damage based on where it is used.

DoorHitSound#

Type:

string

Default:

BaseballBatHit

No description

DoubleClickRecipe#

Type:

Any

No description

DropSound#

Type:

string

No description

Eattime#

Type:

Any

No description

EatType#

Type:

Any

No description

EjectAmmoSound#

Type:

string (block: sound)

No description

EjectAmmoStartSound#

Type:

string (block: sound)

No description

EjectAmmoStopSound#

Type:

string (block: sound)

No description

enduranceChange#

Type:

Any

No description

EnduranceMod#

Type:

float

Default:

1.0

Needs:

ItemType = base:weapon

See UseEndurance for more details.

engineLoudness#

Type:

Any

No description

EquippedNoSprint#

Type:

Any

No description

EquipSound#

Type:

string (block: sound)

No description

EvolvedRecipe#

Type:

Any

List of evolved recipes this item can be used in.

EvolvedRecipeName#

Type:

Any

No description

ExplosionDuration#

Type:

integer

Needs:

ItemType = base:weapon

See ExplosionRange for more details.

ExplosionPower#

Type:

integer

Needs:

ItemType = base:weapon

If set above 0, the explosion will burn tiles and set fire to them based on the provided fireStartingChance

ExplosionRange#

Type:

integer

Needs:

ItemType = base:weapon

FireStartingChance out of 100 is a chance of the explosion to set on fire tiles and burn characters in the ExplosionRange. A value above 100 means the explosion will always set on fire tiles and burn characters, while a value of 0 means it will never set on fire tiles nor burn characters. Each tiles in the explosion range will run the FireStartingChance check independently, so a value of 50 means that on average half of the tiles in the explosion range will be set on fire.

SmokeRange sets the range of the smoke effect. Squares in this range also can be set on fire individually based on FireStartingChance.

FireRange will set every tiles in the provided range on fire.

FireStartingEnergy is an extra check added on top of all of these whenever a fire is attempted to be started. Will set the energy of the fire which impacts how strong is is. A value of 0 means no fire is started. Vegetation tiles provide a net bonus of 50 in energy to the fire being created. The created fire will have a life expectency between 300 and 600 (unclear on the units).

ExplosionSound can be used to set the sound played when the explosion happens, while ExplosionDuration can be used to set the duration of the explosion effect, which is especially useful for smoke bombs.

ExplosionSound#

Type:

string (block: sound)

See ExplosionRange for more details.

ExplosionTimer#

Type:

Any

No description

FabricType#

Type:

Any

No description

fatigueChange#

Type:

Any

No description

FillFromDispenserSound#

Type:

Any

No description

FillFromLakeSound#

Type:

Any

No description

FillFromTapSound#

Type:

Any

No description

FillFromToiletSound#

Type:

Any

No description

FireFuelRatio#

Type:

Any

Attributes:

Useless

No description

FireMode#

Type:

string

Needs:

ItemType = base:weapon

FireModePossibilities lists the available fire modes of the weapon, and the player can automatically switch between them with the relevant keybind. FireMode sets the default fire mode of the weapon, which is the one it will spawn with.

The vanilla fire modes are:

  • Single

  • Auto

Other values are not supported by the game and will be considered as Single.

FireModePossibilities#

Type:

array (array of string, separator: ‘/’)

Needs:

ItemType = base:weapon; FireMode

See FireMode for more details.

FireRange#

Type:

Any

Needs:

ItemType = base:weapon

See ExplosionRange for more details.

FireStartingChance#

Type:

integer

Needs:

ItemType = base:weapon

See ExplosionRange for more details.

FireStartingEnergy#

Type:

integer

Needs:

ItemType = base:weapon

No description

FishingLure#

Type:

Any

No description

fluReduction#

Type:

Any

No description

FoodSicknessChange#

Type:

Any

No description

FoodType#

Type:

Any

No description

GoodHot#

Type:

Any

No description

GunType#

Type:

Any

No description

HaveChamber#

Type:

boolean

Default:

True

Whether the weapon has a chamber that can hold a round in addition to its magazine.

HeadCondition#

Type:

Any

No description

HeadConditionLowerChanceMultiplier#

Type:

float

Default:

1.0

No description

HeadConditionMax#

Type:

Any

No description

HearingModifier#

Type:

float

Default:

1.0

No description

HerbalistType#

Type:

Any

No description

Hidden#

Type:

Any

No description

HitAngleMod#

Type:

Any

No description

HitChance#

Type:

integer

Needs:

ItemType = base:weapon

HitChance is a stat which is directly applied to a HandWeapon while HitChanceModified is applied to weapon parts.

The initial hitchance is determined by the following configuration:

HitChance = min(HitChance, CombatConfigKey.MAXIMUM_START_TO_HIT_CHANCE)

MAXIMUM_START_TO_HIT_CHANCE is a configuration of the combat system of Project Zomboid. In this case, the default value is 95.0, which means the initial HitChance cannot be above 95.0.

Below is a table listing the different elements which can influence the hit chance of a weapon:

Element

Type

Description

Formula

AimingPerkHitChanceModifier and aiming skill of the character

Weapon parameter

The aiming level of the character impacts the player’s hit chance.

HitChance += AimingPerkHitChanceModifier * Aiming level

Sight bonus / penalty

Weapon parameter

In the formula, sightWindowBonus refers to the bonus from MinSightRange and MaxSightRange. sightlessBonus on the other hand is a simpler parameter which uses a distance falloff when there is not active sight. The best path is used for the better result.

HitChance += max(sightlessBonus - sightlessAimDelayPenalty, sightWindowBonus - sightWindowAimDelayPenalty)

Moodles penalty

Player condition

Being panicked, stressed, tired, drunk or lacking endurance will all negatively impact the HitChance.

HitChance -= moodlesPenalty

Weather penalty

Environment

Wind, rain, fog, low-light will all negatively impact the HitChance.

HitChance -= weatherPenalty

Movement penalty

Player condition

The shooter speed and the distance will negatively impact the HitChance.

HitChance -= movementPenalty

Arm pain penalty

Player condition

The character’s level of pain will impact its aiming.

HitChance -= armPainPenalty

Headgear vision penalty

Player condition

Headgear will impact aiming, if the relevant sandbox option is enabled.

HitChance -= headgearVisionPenalty

The final obtained value of HitChance is clamped against the MINIMUM_TO_HIT_CHANCE and MAXIMUM_TO_HIT_CHANCE, both respectively equal to 5.0 and 100.0 by default.

At point-blank range, all combined penalties are scaled toward zero, so close shots are always more forgiving. The HitChance parameter will set the floor for all players while AimingPerkHitChanceModifier will increase accuracy with the level of aiming of the player. Low base and high modifier makes the gun terrible while unskilled but excellent with investment in aiming.

HitChanceModifier#

Type:

integer

Needs:

ItemType = base:weaponpart

See HitChance for more details.

HitFloorSound#

Type:

string (block: sound)

Default:

BatOnFloor

Needs:

ItemType = base:weapon

No description

HitSound#

Type:

string (block: sound)

Default:

BaseballBatHit

Needs:

ItemType = base:weapon

No description

HungerChange#

Type:

Any

No description

Icon#

Type:

string

Default:

None

Used to specify the icon of the item, usually used in the inventory and crafting menus to easily recognize the item. The icon file needs to be located inside the media/textures/ folder and the file name must start with Item_, and be of the extension .png.

📁 media
  📁 textures
    📄 Item_iconName.png

When referencing the icon in the item script, you should not include the Item_ prefix and the .png extension. For example, to reference the icon file above in the item script:

Icon = iconName,

Subfolders#

Subfolders are not directly supported, but you can use some tricks to have them working. Here’s a simple example:

Icon = subFolder/iconName,

Means your folder structure should be:

📁 media
  📁 textures
    📁 Item_subFolder
      📄 iconName.png

Notice how the Item_ prefix is not on the file but on the folder in this case.

Food icons#

Icons can be specified for rotten, cooked and burned food (ItemType = base:food,) by adding the following suffix to the icon files:

  • Rotten or Spoiled for food that has rotten, meaning has passed the DaysTotallyRotten value.

  • Cooked for food that has been cooked, meaning has passed the MinutesToCook value.

  • Overdone or Burnt for food that has been cooked to the point of burning, meaning has passed the MinutesToBurn value.

For example, take a food item with the icon file defined as such:

Icon = iconName,

To add variants based on food condition, you would have the following file structure:

📁 media
  📁 textures
    📄 Item_iconName.png
    📄 Item_iconNameCooked.png
    📄 Item_iconNameRotten.png
    📄 Item_iconNameBurnt.png

IconColorMask#

Type:

Any

No description

IconFluidMask#

Type:

Any

No description

IconsForTexture#

Type:

array (array of string, separator: ‘;’)

No description

IdleAnim#

Type:

string

Default:

Idle

No description

ImpactSound#

Type:

string (block: sound)

Default:

BaseballBatHit

Needs:

ItemType = base:weapon

No description

InsertAllBulletsReload#

Type:

Any

No description

InsertAmmoSound#

Type:

string (block: sound)

No description

InsertAmmoStartSound#

Type:

string (block: sound)

No description

InsertAmmoStopSound#

Type:

string (block: sound)

No description

Insulation#

Type:

Any

No description

InverseCoughProbability#

Type:

Any

No description

InverseCoughProbabilitySmoker#

Type:

Any

No description

IsAimedFirearm#

Type:

boolean

Needs:

ItemType = base:weapon; MaxAmmo

IsAimedFirearm enables the entire aimed-firearm subsystem: ballistics controller, reticle, muzzle flash, firearm-specific condition handling and ballistics-base target detection. Without it the weapon falls back to melee sweep logic.

Set to true for any normal gun. Distinct from Ranged which marks the item as a ranged weapon for the animations conditions.

IsAimedHandWeapon#

Type:

boolean

Needs:

ItemType = base:weapon

No description

IsCookable#

Type:

boolean

No description

IsDung#

Type:

boolean

No description

IsHighTier#

Type:

Any

No description

IsPortable#

Type:

Any

No description

IsTelevision#

Type:

Any

No description

IsWaterSource#

Type:

Any

No description

ItemAfterCleaning#

Type:

Any

No description

ItemType#

Type:

string (required)

Defines the class of the item which will impact which parameters the item can take and its properties as well as how it is used by the player. Clothing for instance will handle differently their texture and model in comparison to the other type of items, containers can hold items and weapons can be used by the player to attack and deal damage. You cannot use a custom class of item and only the ones accepted by the game.

Allowed values:

  • base:alarmclock

  • base:alarmclockclothing

  • base:animal

  • base:clothing

  • base:container

  • base:drainable

  • base:food

  • base:key

  • base:literature

  • base:map

  • base:moveable

  • base:normal

  • base:radio

  • base:weapon

  • base:weaponpart

ItemWhenDry#

Type:

Any

No description

JamGunChance#

Type:

float

Default:

1.0

Needs:

ItemType = base:weapon

Base probability of a jam on each trigger pull. Final jam roml also scales with the sandbox jam multiplier, current gun condition (lower condition = higher jam chance), and low Aiming/Strength.

JamGunChance = 1 is already low. Setting it to 0 basically disables jams from this weapon. Higher values makes the gun unreliable and punishes neglecting the gun or unskilled use.

KeepOnDeplete#

Type:

Any

No description

KnockBackOnNoDeath#

Type:

Any

No description

KnockdownMod#

Type:

float

Default:

1.0

No description

LearnedRecipes#

Type:

Any

No description

LightDistance#

Type:

Any

No description

LightStrength#

Type:

Any

No description

Lipids#

Type:

Any

No description

LowLightBonus#

Type:

Any

No description

LvlSkillTrained#

Type:

integer

Default:

-1

No description

magazine_subject#

Type:

Any

No description

MagazineType#

Type:

string (block: item, with module)

Needs:

ItemType = base:weapon; IsAimedFirearm = True

See AmmoType for more details.

MakeUpType#

Type:

Any

No description

ManuallyRemoveSpentRounds#

Type:

Any

No description

Map#

Type:

Any

No description

MaxAmmo#

Type:

integer

No description

MaxCapacity#

Type:

integer

Default:

-1

No description

MaxChannel#

Type:

integer

Default:

108000

No description

MaxDamage#

Type:

float

Default:

1.5

Rolls the hit damage of the weapon between MinDamage and MaxDamage.

MaxHitcount#

Type:

integer

Default:

1000

Needs:

ItemType = base:weapon

MaxHitcount sets the maximum number of targets the weapon can hit with one attack. For ranged weapons, it will determine how many targets a single shot can hit. For melee weapons, a single swing can hit multiple targets if the relevant sandbox option allows it (Weapon Multi-Hit).

When PiercingBullets is true, a shot continues past the first target and registers on collinear targets behind it. Each subsequent pierced target receives reduced damage (damage / PIERCING_BULLET_DAMAGE_REDUCTION). Targets must be within approximatively 1 degree of each other in angle to qualify.

Keep MaxHitcount to 1 for a standard rifle, and set it to 2 with PiercingBullets to have AP rounds behavior (M16A2 for example).

MaxItemSize#

Type:

Any

No description

MaxRange#

Type:

float

Default:

1.0

MaxRange is a stat which is directly applied to a HandWeapon while MaxRangeModifier is applied to weapon parts.

The MaxRange of a weapon is used to determine the maximum distance the weapon can shoot. Targets beyond effectiveMaxRange calculated with the formula below simply can’t be reached, the parameter is a hard cutoff, not a penalty in damage or anything like that.

effectiveMaxRange = MaxRange + AimingPerkRangeModifier x (AimingLevel / 2.0)

All rifles from the base game have a AimingPerkRangeModifier of 0, so aiming level has no effect on the range of guns. Set it above 0 to give skilled players extra reach.

MaxRangeModifier#

Type:

float

Needs:

ItemType = base:weaponpart

See MaxRange for more details.

MaxSightRange#

Type:

float

Needs:

ItemType = base:weapon, base:weaponpart

MinSightRange and MaxSightRange define the optimal sight window, to be more specific, the distance band where hits and critical hits bonuses peak.

The aiming skill and eagle eyed will impact these values:

effectiveMin = MinSightRange x (1 - AimingLevel / 30)
effectiveMax = MaxSightRange x (1 + AimingLevel / 30) x (EagleEyed ? 1.2 : 1.0)

At aiming 10, the minimum shrinks by 33% and the max grows by 33%, which widens the window significantly. When the trait Short Sighted is present and the character doesn’t wear glasses, the effectiveMax equals effectiveMin, making the entire bonus window disappear.

Inside the the effectiveMin and effectiveMax window, the bonus follows a Gaussian with the bonus peaking at the midpoint. Aim-delay penalty is also reduced inside the window.

Below effectiveMin, a small linear penalty is applied as the gun is not suited for point-blank. Above effectiveMax, a growing quadratic penalty is applied, the bonus degrades rapidly past the edge.

A CQC gun should have a low MaxSightRange while a marksman riffle should have a high MinSightRange with a wide window.

MechanicsItem#

Type:

Any

No description

MediaCategory#

Type:

Any

No description

Medical#

Type:

Any

No description

MetalValue#

Type:

Any

No description

MicRange#

Type:

Any

No description

MinAngle#

Type:

float

Default:

1.0

Needs:

ItemType = base:weapon

For IsAimedFirearm set to true, the ballistics controller handles target detection and does not use MinAngle in the ranged hit-chance formula. These serve one narrow purpose: the isMeleeTargetTooCloseToShoot() check, detecting if a target is so close it should trigger a melee strike instead of a shot.

MinAngle is a dot-product threshold (-1 to 1). Values near 1.0 mean the target must be almost directly in front to trigger the melee-swap check, while lower values widen the angle.

AimingPerkMinAngleModifier is parsed and stored and impacts the minimum angle with the following formula:

effectiveMinAngle = MinAngle - AimingPerkMinAngleModifier * Aiming level

MinChannel#

Type:

integer

Default:

88000

No description

MinDamage#

Type:

float

See MaxDamage for more details.

MinimumSwingtime#

Type:

Any

No description

MinRange#

Type:

float

Hard minimum attack distance. If the target is closer than MinRange, the ballistics controller does not register the shot and the game may force a melee swap. This is a binary threshold, not a penalty band. Separate from MinSightRange.

Long rifles should be hard to use in tight spaces. 0.2 to 0.35 is a small gap but 0.61 is noticeably limiting indoors.

MinSightRange#

Type:

float

Needs:

ItemType = base:weapon, base:weaponpart

See MaxSightRange for more details.

MinutesToBurn#

Type:

float

Default:

120.0

Needs:

ItemType = base:food; IsCookable = True

How many in-game minutes it takes to burn the food. This value must be higher than MinutesToCook.

In comparison with MinutesToCook, this parameter is not available for base:drainable ItemTypes.

MinutesToCook#

Type:

float

Default:

60.0

Needs:

ItemType = base:food, base:drainable; IsCookable = True

How many in-game minutes it takes to cook the food. This value must be smaller than MinutesToBurn.

ModelWeaponPart#

Type:

Any

Attributes:

Can be duplicated

No description

MountOn#

Type:

Any

No description

MultipleHitConditionAffected#

Type:

boolean

Default:

True

No description

MuzzleFlashModelKey#

Type:

Any

No description

NeckProtectionModifier#

Type:

float

Default:

1.0

No description

needtobeclosedoncereload#

Type:

Any

No description

NoiseDuration#

Type:

Any

No description

NoiseRange#

Type:

Any

No description

NoTransmit#

Type:

Any

No description

NPCSoundBoost#

Type:

float

Default:

1.0

No description

NumberOfPages#

Type:

integer

Default:

-1

No description

NumLevelsTrained#

Type:

integer

Default:

1

No description

OnBreak#

Type:

Any

No description

OnCooked#

Type:

Any

No description

OnCreate#

Type:

Any

No description

OnEat#

Type:

Any

No description

OpeningRecipe#

Type:

Any

No description

OpenSound#

Type:

Any

No description

OriginX#

Type:

Any

No description

OriginY#

Type:

Any

No description

originZ#

Type:

Any

No description

OtherHandRequire#

Type:

Any

No description

OtherHandUse#

Type:

Any

No description

Packaged#

Type:

Any

No description

Padlock#

Type:

Any

No description

PageToWrite#

Type:

Any

No description

painReduction#

Type:

Any

No description

PartType#

Type:

Any

No description

PhysicsObject#

Type:

string (block: item, with module)

Needs:

ItemType = base:weapon

Provides another item (or itself) as a throwable object. When used, the item will be thrown instead of used as an actual in hands weapon.

PiercingBullets#

Type:

boolean

Needs:

ItemType = base:weapon; IsAimedFirearm = True; MaxHitcount

See MaxHitcount for more details.

PlacedSprite#

Type:

Any

No description

PlaceMultipleSound#

Type:

Any

No description

PlaceOneSound#

Type:

string

No description

PoisonPower#

Type:

Any

No description

PourType#

Type:

Any

No description

primaryAnimMask#

Type:

Any

No description

Projectilecount#

Type:

integer

Default:

1

Needs:

ItemType = base:weapon; IsAimedFirearm = True; RangeFalloff = True

Only active when the weapon is ranged and has RangeFalloff set to true. In that mode, the ballistics controller generates multiple spread projectiles. The field is never read when RangeFalloff is false.

Inert for standard rifles. Required only for shotgun-style spread.

ProjectileSpread#

Type:

Any

No description

ProjectileSpreadModifier#

Type:

Any

No description

ProjectileWeightCenter#

Type:

float

Default:

1.0

No description

ProtectFromRainWhenEquipped#

Type:

Any

No description

Proteins#

Type:

Any

No description

PushBackMod#

Type:

float

Default:

1.0

Needs:

ItemType = base:weapon

Scales the magnitude of the hit-reaction push applied to the target character. A higher value will increase the time the target is staggered. It will also impact the spread of blood.

Higher gives a more weighty, impactful feel.

PutInSound#

Type:

Any

No description

RackAfterShoot#

Type:

Any

No description

RackSound#

Type:

Any

No description

RainFactor#

Type:

Any

No description

Ranged#

Type:

boolean

Needs:

ItemType = base:weapon

See IsAimedFirearm for more details.

RangeFalloff#

Type:

boolean

Needs:

ItemType = base:weapon

No description

ReadType#

Type:

Any

No description

RecoilDelay#

Type:

Any

Needs:

ItemType = base:weapon

RecoilDelay is a stat which is directly applied to a HandWeapon while AimingTimeModifier is applied to weapon parts. Weapon attachments will add or subtract from RecoilDelay directly.

Controls how long post-shot recovery takes before aim settling can begin. High values means the gun has a huge kick and forces a pause. Lower values is a flat, fast and snappy gun. Strength and aiming will both reduce the recoil delay. Holding the gun one-handed will negatively impact the recoil handling. The following formula is used:

effectiveDelay = RecoilDelay
              * (1 - AimingLevel / 40)
              * (1 - (StrengthLevel * 2 - 10) / 40)
              * (one-handed penalty: * 1.3 if primary hand only, secondary empty)

Aim countdown starts when the recoil delay counter is less than effectiveDelay * AimingLevel / 30. Higher aiming also lets aim recovery start earlier in the recoil window.

RecoilDelayModifier#

Type:

Any

Needs:

ItemType = base:weaponpart

See RecoilDelay for more details.

ReduceInfectionPower#

Type:

Any

No description

Reloadtime#

Type:

Any

No description

ReloadTimeModifier#

Type:

Any

No description

RemoteController#

Type:

Any

No description

RemoteRange#

Type:

Any

No description

RemoveNegativeEffectOnCooked#

Type:

Any

No description

RemoveOnBroken#

Type:

boolean

Default:

True

No description

RemoveUnhappinessWhenCooked#

Type:

Any

No description

ReplaceInPrimaryHand#

Type:

Any

No description

ReplaceInSecondHand#

Type:

Any

No description

ReplaceOnCooked#

Type:

Any

No description

ReplaceOnDeplete#

Type:

Any

No description

ReplaceOnExtinguish#

Type:

Any

No description

ReplaceOnRotten#

Type:

Any

No description

ReplaceOnUse#

Type:

Any

No description

RequireInHandOrInventory#

Type:

Any

No description

RequiresEquippedBothHands#

Type:

boolean

No description

Researchablerecipes#

Type:

array (array of string, separator: ‘;’)

No description

RunAnim#

Type:

string

Default:

Run

No description

RunSpeedModifier#

Type:

float

Default:

1.0

No description

ScaleWorldIcon#

Type:

float

Default:

1.0

No description

ScratchDefense#

Type:

Any

No description

secondaryAnimMask#

Type:

Any

No description

SensorRange#

Type:

Any

No description

Sharpness#

Type:

Any

No description

ShellFallSound#

Type:

string (block: sound)

Needs:

ItemType = base:weapon

No description

ShoutMultiplier#

Type:

float

Default:

1.0

No description

ShoutType#

Type:

Any

No description

SkillTrained#

Type:

string

No description

SmokeRange#

Type:

Any

No description

SoundGain#

Type:

float

Default:

1.0

No description

SoundMap#

Type:

Any

Attributes:

Can be duplicated

No description

SoundParameter#

Type:

Any

No description

SoundRadius#

Type:

Any

No description

SoundVolume#

Type:

Any

No description

SpawnWith#

Type:

Any

No description

Spice#

Type:

Any

No description

SplatBloodOnNoDeath#

Type:

Any

No description

SplatNumber#

Type:

integer

Default:

2

No description

SplatSize#

Type:

float

Default:

1.0

No description

StaticModel#

Type:

string (block: model, with module)

No description

StaticModelsByIndex#

Type:

array (array of string, separator: ‘;’)

No description

StompPower#

Type:

float

Default:

1.0

No description

StopPower#

Type:

float

Default:

5.0

Needs:

ItemType = base:weapon

See CriticalChance for more details.

StressChange#

Type:

Any

No description

SubCategory#

Type:

string

No description

SurvivalGear#

Type:

Any

No description

suspensionCompression#

Type:

Any

No description

suspensionDamping#

Type:

Any

No description

SwingAmountBeforeImpact#

Type:

Any

No description

SwingAnim#

Type:

string

Default:

Rifle

No description

SwingSound#

Type:

string (block: sound)

Default:

BaseballBatSwing

Needs:

ItemType = base:weapon

No description

Swingtime#

Type:

float

Default:

1.0

No description

Tags#

Type:

array (array of string, separator: ‘;’)

A list of tags to assign to the item. Tags are used by the game to easily identify properties of the items from the Lua or Java. This can notably be used in craftRecipes.

For example:

Tags = base:egg;base:hasmetal,

You can find a list of all tags on the wiki. The wiki also provides a list of every items (per full type) associated to tags here.

To create a custom tag, you have to first create its definition in your mod’s registries. In the registries.lua file, define the following by renaming the various elements to fit your mod name, id etc:

YourModRegistry = {}
YourModRegistry.YOUR_TAG_NAME = ItemTag.register("yourmodid:yourtagname")

You can then use that tag yourmodid:yourtagname in your item definition. And you can use the stored ItemTag reference YourModRegistry.YOUR_TAG_NAME in your Lua code.

ThirstChange#

Type:

Any

No description

ticksPerEquipUse#

Type:

integer

Default:

30

No description

ToHitModifier#

Type:

float

Default:

1.0

No description

Tooltip#

Type:

Any

No description

TorchCone#

Type:

Any

No description

TorchDot#

Type:

float

Default:

0.96

No description

TransmitRange#

Type:

Any

No description

Trap#

Type:

boolean

Default:

False

No description

TreeDamage#

Type:

Any

No description

triggerExplosionTimer#

Type:

Any

No description

TwoHandWeapon#

Type:

boolean

Needs:

ItemType = base:weapon

TwoHandWeapon marks the weapon as a two-handed weapon. RecoilDelay gets a x1.3 penalty when the weapon is held one-handed instead of two handed. RequiresEquippedBothHands enforces the equip restriction in the context menu.

TwoWay#

Type:

Any

No description

Type#

Type:

Any

Used to set the class of the item, which will influence parameters available.

Warning

Deprecated (since version 42.13.0)

Use ItemType instead.

UnequipSound#

Type:

string

No description

UnhappyChange#

Type:

Any

No description

UseDelta#

Type:

float

Default:

0.03125

No description

UseEndurance#

Type:

boolean

Default:

True

Needs:

ItemType = base:weapon

If true, the weapon will consume stamina on use based on the weapon weight, EnduranceMod, fatigue modifiers and traits.

For guns, it is preferable to keep this as False.

UsesBattery#

Type:

Any

No description

UseSelf#

Type:

Any

No description

UseWhileEquipped#

Type:

boolean

Default:

True

No description

UseWhileUnequipped#

Type:

Any

No description

UseWorldItem#

Type:

Any

No description

VehiclePartModel#

Type:

Any

No description

VehicleType#

Type:

Any

No description

VisionModifier#

Type:

float

Default:

1.0

No description

VisualAid#

Type:

Any

No description

WaterResistance#

Type:

Any

No description

WeaponHitArmourSound#

Type:

Any

No description

WeaponLength#

Type:

float

Default:

0.4

No description

WeaponReloadType#

Type:

string

Default:

handgun

Needs:

ItemType = base:weapon; IsAimedFirearm = True

See AmmoType for more details.

WeaponSprite#

Type:

Any

No description

WeaponSpritesByIndex#

Type:

Any

No description

WeaponWeight#

Type:

float

Default:

1.0

No description

Weight#

Type:

float

Default:

1.0

Sets the weight of the item, or more commonly refered to as a encumbrance. Weapon parts will impact the weight of the weapon when attached. Will also impact stamina drain when UseEndurance is true.

WeightEmpty#

Type:

Any

No description

WeightModifier#

Type:

Any

No description

WeightReduction#

Type:

Any

No description

Wet#

Type:

Any

No description

WetCooldown#

Type:

Any

No description

wheelFriction#

Type:

Any

No description

WindResistance#

Type:

Any

No description

WithDrainable#

Type:

Any

No description

WithoutDrainable#

Type:

Any

No description

WorldObjectSprite#

Type:

Any

No description

WorldRender#

Type:

Any

No description

WorldStaticModel#

Type:

string (block: model, with module)

No description

WorldStaticModelsByIndex#

Type:

array (array of string, separator: ‘;’)

No description

On this page
Show Source