Details on the improved modding tag system in 41.69

[Batsphinx]

New Tag Info!

 

- Several new Tags were added to the item scripts, and their functionality added to the lua code.
- This allows for modders to add new items that seamlessly work with the game in several places, such as adding new fully-functional Sledgehammer items, or adding new Gasoline containers.
- The new code includes safeguards to prevent vanilla items that have been overwritten by mods, such as Better/Improved Item mods, from having their utility broken by this update in most circumstances. But if you do experience issues using items, try disabling mods of that nature.
- However, for the sake of continued compatibility with future changes to items in PZ, modders should not overwrite item scripts, and should use the DoParam function to modify script items instead.
- How to use DoParam to properly modify item scripts is demonstrated at the end of this documentation.

 

New Tags

BluePen, Corkscrew, Disinfectant, DullKnife, Egg, EmptyPetrol, Eraser, Fork, GasMask, Glue, HazmatSuit, HeavyItem, Liquor, Milk, MortarPestle, Pen, Pencil, Petrol, Razor, RedPen, ReloadFastBullets, ReloadFastShells, RemoveBullet, RemoveGlass, Scissors, SharpKnife, Sledgehammer, Spoon, StartFire, Sugar, Tape, WeldingMask.

 

Recipe Changes

- Denim Strips can now be used in recipes that require Ripped Sheets.
- Suture Needles now cannot be used in the Make Mattress recipe; they're specialized single-use medical supplies and not actual sewing needles.
- Making Jars of vegetables should now require one hunger unit of Sugar instead of consuming entire bags of Sugar. Other recipes requiring Sugar will also work likewise, consuming hunger units instead of entire Sugar items. That issue was due from Sugar being changed from a drainable item to a food item.
- The Make Molotov Cocktail Recipe using Bourbon now requires a full bottle of Bourbon to craft a Moltov Cocktail; previously partially-consumed bottle could be used to craft Moltov Cocktails.
- Recipes using Eggs now require whole eggs to use them; previously partially consumed Eggs could be used in them.

 

New Tag Explanations

 

BluePen, Pen, Pencil, RedPen: Used to enable writing in the appropriate color on the map. Add the Write Tag to new mod items with this Tag as well, eg.: "Tags = Write;Pencil," 
Corkscrew, GasMask, HazamatSuit: Currently unused in vanilla; can be used for new mod recipes.
Disinfectant: Used in to disinfect Bandages, etc. In order for items to be used to disinfect wounds in the First Aid Interface they need to have an Alcohol Power parameter set in their script, such as " AlcoholPower = 3,"
DullKnife: Used in recipes that can utilize dull knife utensils, such as Bread Knives and Butter Knives.
Egg: Used in recipes that require Eggs.
EmptyPetrol: Used to determine if a container can be used to contain Gasoline. These items will also require a parameter such as "ReplaceTypes = PetrolSource NEW_PETROL_CONTAINER," where NEW_PETROL_CONTAINER is the item that replaces the Empty Petrol container when it is filled with Gasoline.
Eraser: Used to erase notations in the map.
Fork, Spoon: Used to determine if the player has a Fork or Spoon for eating animations.
Glue: Unused in vanilla, can be used to determine if an item counts as Glue for new mod recipes.
Liquor: Used in recipes for making Molotov Cocktails and disinfecting Bandages.
HeavyItem: Used to determine if items are heavy oversized objects that need to be held in both hands to be in the inventory, such as Generators and Corpses.
Milk: Used in recipes that require Milk.
MortarPestle: Used in recipes to make Poultices.
Petrol: Used to determine if a container holds Gasoline. These items will also require a parameter such as "ReplaceOnDeplete = NEW_EMPTY_PETROL_CONTAINER," where NEW_EMPTY_PETROL_CONTAINER is the item that replaces the Empty Petrol container when it is emptied of Gasoline.
Razor, Scissors: Used to determine if an item functions as a Razor or Scissors for cutting Hair and Beards.
ReloadFastBullets: Improves the reload speed of firearms that use non-Shotgun Shell ammunition when equipped.
ReloadFastShells: Improves the reload speed of firearms use Shotgun Shell ammunition when equipped.
RemoveBullet: Used to determine if an item can be used to remove Bullets from injuries in the First Aid Interface.
RemoveGlass: Used to determine if an item can be used to remove Glass from injuries in the First Aid Interface.
SharpKnife: Used in recipes that require a sharp cutting instrument.
Sledgehammer: Used to determine if an item can Destroy tiles (if the Sledgehammer Destruction option is enabled in Sandbox/Server settings) as well as if the item counts as a Sledgehammer for recipes.
StartFire: Used to determine if an object can be used to Burn Corpses and ignite Campfires, BBQs and Fireplaces. Does not work for lighting Cigarettes and Molotov Cocktails.
Tape: Unused in vanilla, can be used to determine if an item counts as adhesive Tape for new mod recipes.
WeldingMask: Used to determine if an object counts as a Welder Mask for recipes, Metalwork Construction, and Disassembling tiles.

 

Script Example of How To Use New Item Tags For New Recipes

- Note that Tags do not work for the Fixing recipes.
- Use the format [Recipe.GetItemTypes.TAG_NAME_HERE] in the script block as follows for new recipes.

 

module Base
{ 
    recipe Make Stake From Sturdy Stick
    {
        WoodenStick,
        keep [Recipe.GetItemTypes.SharpKnife]/MeatCleaver,

        Result:Stake,
        Time:80.0,
        Category:Survivalist,
        OnGiveXP:Recipe.OnGiveXP.WoodWork5,
    }
}
    
- Tags that can be used in recipes this way are in the beginning of media/lua/server/recipecode.lua/server/recipecode.
- Note: Not all new tags have this utility for recipes;
- To add new Tag functionality for recipes make a lua file in media/server with the following code; this can also be used to make new mod Tags usable for new mod Recipes:

    require "recipecode":
    function Recipe.GetItemTypes.TAG_NAME(scriptItems)
        scriptItems:addAll(getScriptManager():getItemsTag("TAG_NAME"))
    end

 

Script Example Of How To Add New Sledgehammers
- This must be in a txt file in the directory media/scripts.

    

module Base
    {   
        item SuperKatana
        {
            DisplayCategory = Weapon,
            MaxRange    =    1.4,
            WeaponSprite    =    Katana,
            MinAngle    =    0.8,
            Type    =    Weapon,
            MinimumSwingTime    =    3,
            HitFloorSound    =    KatanaHit,
            ImpactSound    =    KatanaHit,
            DoorHitSound = KatanaHit,
            HitSound    =    KatanaHit,
            SwingSound = KatanaSwing,
            KnockBackOnNoDeath = TRUE,
            SwingAmountBeforeImpact    =    0.02,
            Categories    =    LongBlade,
            Weight    =    2,
            ConditionLowerChanceOneIn    =    15,
            PushBackMod    =    0.5,
            SubCategory    =    Swinging,
            ConditionMax    =    10,
            MaxHitCount    =    3,
            DoorDamage    =    8,
            SwingAnim    =    Bat,
            CriticalChance    =    35,
            CritDmgMultiplier = 6,
            DisplayName    =    Super Katana,
            MinRange    =    0.61,
            SwingTime    =    3,
            HitAngleMod    =    -30,
            KnockdownMod    =    0,
            Icon    =    Katana,
            RunAnim    =    Run_Weapon2,
            BreakSound  =   KatanaBreak,
            TreeDamage  =   1,
            CriticalChance    =    30,
            CritDmgMultiplier = 10,
            MinDamage    =    8,
            MaxDamage    =    8,
            BaseSpeed = 1,
            WeaponLength = 0.3,
            DamageCategory = Slash,
            DamageMakeHole = TRUE,
            TwoHandWeapon = TRUE,
            WeaponLength = 0.4,
            AttachmentType = BigBlade,
            Tags = Sledgehammer,
        }
    }

 

Script Examples Of How To Add New Petrol Containers
- This must be in a txt file in the directory media/scripts.

    module Base

 

    {
        item SmallEmptyPetrolCan
        {
            DisplayCategory = VehicleMaintenance,
            Weight    =    0.8,
            Type    =    Normal,
            DisplayName    =    Small Empty Gas Can,
            Icon    =    Petrol,
            StaticModel = SmallGasCan,
            SurvivalGear = TRUE,
            ReplaceInSecondHand = Bag_GasCan_LHand holdingbagleft,
            ReplaceInPrimaryHand = Bag_GasCan_RHand holdingbagright,
            WorldStaticModel = SmallGasCan_Ground,
            Tags = EmptyPetrol,
            ReplaceTypes = PetrolSource SmallPetrolCan,
        }
        item SmallPetrolCan
        {
            DisplayCategory = VehicleMaintenance,
            Weight    =    2.5,
            Type    =    Drainable,
            UseWhileEquipped    =    FALSE,
            UseDelta    =    0.25,
            DisplayName    =    Small Gas Can,
            Icon    =    Petrol,
            ReplaceOnDeplete    =    SmallEmptyPetrolCan,
            StaticModel = SmallGasCan,
            ReplaceInSecondHand = Bag_GasCan_LHand holdingbagleft,
            ReplaceInPrimaryHand = Bag_GasCan_RHand holdingbagright,
            WorldStaticModel = SmallGasCan_Ground,
            Tags = Petrol,
        }
        item LargeEmptyPetrolCan
        {
            DisplayCategory = VehicleMaintenance,
            Weight    =    3.2,
            Type    =    Normal,
            DisplayName    =    Large Empty Gas Can,
            Icon    =    Petrol,
            StaticModel = LargeGasCan,
            SurvivalGear = TRUE,
            ReplaceInSecondHand = Bag_GasCan_LHand holdingbagleft,
            ReplaceInPrimaryHand = Bag_GasCan_RHand holdingbagright,
            WorldStaticModel = LargeGasCan_Ground,
            Tags = EmptyPetrol,
            ReplaceTypes = PetrolSource LargePetrolCan,
        }
        item LargePetrolCan
        {
            DisplayCategory = VehicleMaintenance,
            Weight    =    10,
            Type    =    Drainable,
            UseWhileEquipped    =    FALSE,
            UseDelta    =    0.0625,
            DisplayName    =    Large Gas Can,
            Icon    =    Petrol,
            ReplaceOnDeplete    =    LargeEmptyPetrolCan,
            StaticModel = LargelGasCan,
            ReplaceInSecondHand = Bag_GasCan_LHand holdingbagleft,
            ReplaceInPrimaryHand = Bag_GasCan_RHand holdingbagright,
            WorldStaticModel = LargeGasCan_Ground,
            Tags = Petrol,
        }
        model SmallGasCan
        {
            mesh = GasCan,
            texture = GasCan,
            scale = 0.75,
        }
        model SmallGasCan_Ground
        {
            mesh = WorldItems/Clothing/GasCan,
            texture = GasCan,
            scale = 0.3,
        }
        model LargeGasCan
        {
            mesh = GasCan,
            texture = GasCan,
            scale = 1.5,
        }
        model LargeGasCan_Ground
        {
            mesh = WorldItems/Clothing/GasCan,
            texture = GasCan,
            scale = 0.6,
        }
    }
    
Script and Lua Examples Of How To Add New Petrol and Gasoline Containers Functionality to Vanilla Items
- This must be in a txt file in the directory media/scripts.

    

module Base
    {
        item WhiskeyPetrol
        {
            DisplayCategory = VehicleMaintenance,
            Weight    =    0.7,
            Type    =    Drainable,
            UseWhileEquipped    =    FALSE,
            UseDelta    =    1,
            DisplayName    =    Bottle of Gasoline,
            Icon    =    WhiskeyFull,
            ReplaceOnDeplete    =    WhiskeyEmpty,
            StaticModel = WhiskeyBottle,
            WorldStaticModel = WhiskeyBottleGround,
            Tags = Petrol,
        }
    }

 

- This must be in a lua file in media/lua/server or media/lua/shared to work properly.

    local scriptItem = ScriptManager.instance:getItem("Base.WhiskeyEmpty")
    if scriptItem then
        scriptItem:getTags():add("EmptyPetrol")    
        scriptItem:DoParam("ReplaceTypes = PetrolSource WhiskeyPetrol;WaterSource WhiskeyWaterFull")
    end
    
Script Example Of How To Add A New Multi-Color Pen:
- This must be in a txt file in the directory media/scripts.

  

 module Base
    {
        item MultiColorPen
        {
            DisplayCategory = Household,
            MaxRange    =    0.8,
            WeaponSprite    =    Pen,
            MinAngle    =    0.65,
            Type    =    Weapon,
            MinimumSwingTime    =    2,
            KnockBackOnNoDeath    =    FALSE,
            SwingAmountBeforeImpact    =    0.02,
            Categories    =    Improvised,
            ConditionLowerChanceOneIn    =    1,
            Weight    =    0.1,
            SplatNumber    =    1,
            PushBackMod    =    0.3,
            SubCategory    =    Stab,
            AimingMod    =    0.8,
            ConditionMax    =    2,
            MaxHitCount    =    1,
            IsAimedHandWeapon    =    TRUE,
            DoorDamage    =    0,
            SwingAnim    =    Stab,
            DisplayName    =    Multi-Color Pen,
            MinRange    =    0.61,
            SwingTime    =    2,
            KnockdownMod    =    0,
            SplatBloodOnNoDeath    =    FALSE,
            Icon    =    Pen,
            RunAnim    =    Run_Weapon2,
            IdleAnim    =    Idle_Weapon2,
            TreeDamage  =   0,
            EnduranceMod = 0.5,
            CriticalChance    =    0,
            MinDamage    =    0.1,
            MaxDamage    =    0.1,
            WeaponLength = 0.15,
            Tags = Write;RedPen;BluePen;Pen,
            BreakSound  =   PenBreak,
            HitFloorSound = PenHit,
            ImpactSound    =    PenHit,
            DoorHitSound = PenHit,
            HitSound    =    PenHit,
            SwingSound = PenSwing,
        }
    }

 

Lua Examples of How to Properly Add Tags to Items Instead With lua Code Instead of Overwriting Them With txt Scripts
- This code will all a Hunting Knife to used to shave beards and hair.
- This must be in a lua file to be in media/lua/server or media/lua/shared to work properly.

    local scriptItem = ScriptManager.instance:getItem("Base.HuntingKnife")
    if scriptItem then
        scriptItem:getTags():add("Razor") 
    end
    
- This code will add Eraser functionality to the Pencil item.
- This must be in a lua file to be in media/lua/server or media/lua/shared to work properly.

  

 local scriptItem = ScriptManager.instance:getItem("Base.Pencil")
    if scriptItem then
        scriptItem:getTags():add("Eraser") 
    end

 

Lua Example of How to Properly Modify Existing Vanilla Items With lua Code Instead of Overwriting Them With txt Scripts
- This code will increase the durability of the Katana to be equivalent to that of the Crowbar.
- This must be in a lua file in media/lua/server or media/lua/shared to work properly.

 

    local scriptItem = ScriptManager.instance:getItem("Base.Katana")
    if scriptItem then
        scriptItem:DoParam("ConditionLowerChanceOneIn = 70")
        scriptItem:DoParam("ConditionMax = 15")
    end

[xXMoksXx]

Please add similar tags for light bulbs and batteries so that we can make our own options

[Hugo Qwerty]

Thanks for this, very useful.

 

Can I make a request - can you add a 'MountOnAdd' for use in DoParam?  That would allow additions to the list without needing to replace the list.

 

For exmaple, I need to use:

scriptItem:DoParam("MountOn = Hydrocraft.HCUzi; HuntingRifle; VarmintRifle; Pistol; Pistol2; Pistol3; Revolver; Revolver_Long; AssaultRifle; AssaultRifle2,")

 

It would be nice if I could use:

scriptItem:DoParam("MountOnAdd = Hydrocraft.HCUzi")

 

The current method will cause issues if more than one mod calls DoParam + MountOn on items like Base.IronSight, Base.GunLight, Base.RedDot.

 

For completeness, a 'MountOnRemove' may also be useful - although it's not something I would need.

 

 

Edited April 29, 2022 by Hugo Qwerty
typo

[ProjectSky]

DoParam should use key, value format, not weird "ConditionLowerChanceOneIn = 70" format

 

like this 

DoParam("ConditionLowerChanceOneIn", 100)

[EnigmaGrey]

9 hours ago, ProjectSky said:

DoParam should use key, value format, not weird "ConditionLowerChanceOneIn = 70" format

 

like this 

DoParam("ConditionLowerChanceOneIn", 100)

 

The game can handle either version without issue. Either it'll parse the = immediately and break it into two params or it gets two params. 

[Tchernobill]

@EnigmaGrey

when setting StaticModel, primaryAnimMask and secondaryAnimMask of an item in txt file, the associated item appears in hands.

when calling DoParam (or ItemTweaker mod) on the associated scriptitem for those parameters, the associated item does not appear in hands.

Is there a way to make this work from lua code for StaticModel, primaryAnimMask and secondaryAnimMask ?

 

Also PlanetAlgol explicited this in the code comments of his last mod: Visible Generators and Corpses.

Regards

[Neznajka]

Why did you remove RemoveBarricade tag from some of the hammers? Now I have to go through the whole town again to get the right one.

Edited May 30, 2022 by Neznajka