[Documentation] Modutil Functions

[Hornete]

Hey! I'll be listing some documentation on all of the functions in the scripts/modutil.lua file. All of these functions are very common and were made for Modders to use so I decided to document them all so you might have a better understanding of how to use that function. These functions are populated into your mod environments and can all be used in either modmain.lua or modworldgenmain.lua in your mod.

GetModConfigData

Spoiler

GetModConfigData(optionname)

The GetModConfigData function is used to get the configuration data the user has chosen in the mods configurations list.

Parameters:

• optionname - The name of the configuration you'd like to get data from.

Examples:

Spoiler

TUNING.FOOTBALLHAT_DURABILITY = GetModConfigData(“footballhatdurability”) --TUNING.FOOTBALLHAT_DURABILITY will now be whatever GetModConfigData(“footballhatdurability”) returns

 

 

AddSimPostInit

Spoiler

AddSimPostInit(fn)

The AddSimPostInit function is used to run the passed function at a certain state of the game. The game world is loaded at this state. I personally use this function to generate the currents in my Ocean Currents mod.

Parameters:

• fn - Function to be run on sim

Examples:

Spoiler

AddSimPostInit(function()
	print(“The game is partly initalized and loaded in!”)
end)

 

 

AddClassPostConstruct

Spoiler

AddClassPostConstruct(filepath, fn)

The AddClassPostConstruct lets you make changes to Class’s returned from files. AddClassPostConstruct is commonly used to make changes to widgets, screens, replica components. While it can be used for components, the AddComponentPostInit function is already there to cover that.

Parameters:

• filepath - The file path to the script that passes the Class you'd like to edit.
• fn - The function that will run when the Class is initialized, the game will pass self to this function

Examples:

Spoiler

AddClassPostConstruct("widgets/boatmeter", function(self)
	print(“I’m the boat meter!”)
	self.icon:Hide() --Hides the icon of the boat meter!
end)

AddClassPostConstruct("components/hunger_replica", function(self)
	print(“I’m the replica for the hunger component!”)
end)

 

 

 

The functions below here can only be used in modmain.lua and are excluded from modworldgenmain.lua

 

AddModCharacter

Spoiler

AddModCharacter(name, gender, modes)

The AddModCharacter function is responsible for making sure your custom character shows up in the character select screen.

Parameters:

• name - The prefab name of your modded character
• gender - The gender of your character(This determines the pronouns used for your character.)
  • The current genders that can be used for a character are: (Note: You can totally create your own custom genders if you'd like! Feel free to populate STRINGS.UI.GENDERSTRINGS to create custom pronouns for custom genders. Take a look at how current genders have their strings in scripts/strings.lua)
  • "MALE"
  • "FEMALE"
  • "ROBOT"
  • "NEUTRAL"
  • "PLURAL"
• modes - A table containing information on all the different modes and views of a character the player can view in the wardrobe. Yours will likely only include the ghost model but you can totally add more views if your character is like Wormwood, Wolfgang or Woodie in that they have custom states and transformations.
  • General variables needed for the modes table:
  • type - The specific type assigned with this view
  • anim_bank - The bank of animations this model should use.
  • idle_anim - The idle animation for the model to play
  • scale - The scale of the model
  • offset - A table containing the x and y offsets of the model

Examples:

Spoiler

AddModCharacter("william", "MALE", 
		{
			{type = "ghost_skin", anim_bank = "ghost", idle_anim = "idle", scale = 0.75, offset = {0, 25}},
		}
	)

 

AddModCharacter("wilba", "FEMALE", 
		{
			{type = "ghost_skin", anim_bank = "ghost", idle_anim = "idle", scale = 0.75, offset = {0, 25}},
			{type = "werewilba", anim_bank = "wilson", idle_anim = "idle", scale = 1, offset = {0, 0}},
		}
	)

 

AddAction

Spoiler

AddAction(id, str, fn)

The AddAction function is responsible for adding custom actions into the game.

Be sure to look at the scripts/actions.lua file to find vanilla actions

Parameters:

• id - The id name for your custom action (e.g. "LIGHT", "CHOP")
• str - The pop up string for your action(If this action is meant be to be used by other entities/mobs and not the player then this string will never matter, I like to put something goofy as the text string if it's never meant to be seen haha)
• fn - The function to be executed when the action is performed

Examples:

Spoiler

AddAction("CUSTOMID", "Do Action", function(act)
	--Code here runs when the action is performed
    act.doer.components.hunger:DoDelta(100) --Let's give 100 hunger points to the doer of the action!
end)

 

 

AddPopup

Spoiler

AddPopup(id)

The AddPopup function is used to add new pop ups similar to the cook book, plant registry, wardrobe ui and etc. When your custom popup is added through this function you can access it through the POPUPS global variable and add your own fn to be executed when the popup is activated/deactivated. Popups you add can be activated on and off for players by calling

--”player” is the player you’d like to activate the popup for
player:ShowPopup(POPUPS.YOURPOPUPID, true) --set to true for popup to show up, set to false for pop up to go away

Parameters

• id - The id associated with your custom popup

Examples:

Spoiler

AddPopup("FISHBOOK")

POPUPS.FISHBOOK.fn = function(inst, show) --Function will be run everytime ShowPopup is called for a player
      if inst.HUD then
     	   if not show then
         	   inst.HUD:CloseFishJournalScreen()
   	     elseif not inst.HUD:OpenFishJournalScreen() then
         	   POPUPS.FISHBOOK:Close(inst)
   	     end
       end
end

 

 

 

AddComponentAction

Spoiler

AddComponentAction(actiontype, component, fn)

The AddComponentAction function determines what components have what actions tied to them.

It’s important to note depending on the action type of the component action there will be different parameters for the function you put in the 3rd parameter. I will put the different parameters for each action type here, but in case more action types are ever added, you can find the different parameters for the different action types in scripts/componentactions.lua.

"SCENE" --args: inst, doer, actions, right
"USEITEM" --args: inst, doer, target, actions, right
"POINT" --args: inst, doer, pos, actions, right
"EQUIPPED" --args: inst, doer, target, actions, right
"INVENTORY"--args: inst, doer, actions, right

Parameters:

• actiontype - The action type. There are 5 action types in the game currently. These action types determine when/where and in which context the function will run. The "EQUIPPED" action type for example will make the function run when the entity with the associated component is equipped.
• component - The associated component for actions to be associated with.
• fn - The function to be run when the player is hovering over an entity/item with the associated actiontype and component. The actions table passed through is meant to be populated with the available actions for that component.

Examples:

Spoiler

--When an entity with the "book" component is hovered over in the inventory, the passed fn runs to determine whether or not the "READ" action is an available action
AddComponentAction("INVENTORY", "book", function(inst, doer, actions)
	if doer:HasTag("reader") then
		table.insert(actions, ACTIONS.READ)
	end
end)

 

 

 

AddPlayerPostInit

Spoiler

AddPlayerPostInit(fn)

The AddPlayerPostInit function lets you apply changes to all characters in the game together upon their initialization.

Parameters:

• fn - The fn to be executed upon the initialization of a player
  • Passed Parameters to fn:
  • inst - The player entity

Examples:

Spoiler

AddPlayerPostInit(function(inst)
	print(“i am a player, WAHOO!”)
    	--Code here is applied to every character

	inst:AddTag("reader") --Every player will now get the reader tag, this means they can all read wickerbottom books!
end)

 

 

AddPrefabPostInit

Spoiler

AddPrefabPostInit(prefab, fn)

The AddPrefabPostInit function lets you run code upon the initialization of a prefab (If you are unsure what a prefab is, be sure to check out my poston understanding prefabs!)

All the prefabs in the game can be found in the scripts/prefabs folder.

Parameters:

• prefab - The name of the prefab that you would like to edit.
• fn - The function to be run upon the initialization of an instance of this prefab
  • Passed parameters to fn:
  • inst - The instance of this prefab

Examples:

Spoiler

AddPrefabPostInit(“acorn”, function(inst)
	print(“I am acorn, WAHOO”)
    	--Code here is applied to the prefab you are editing
end)

AddPrefabPostInit("abigail", function(inst)
	if inst.components.health ~= nil then
		inst.components.health:SetMaxHealth(99999) --Let's set 99999 max health for Abigail when she spawns! >:)
	end
end)

 

 

AddPrefabPostInitAny

Spoiler

AddPrefabPostInitAny(fn)

The AddPrefabPostInitAny function is just like the AddPrefabPostInit function, but the passed fn applies to every single prefab in the game! This is useful for applying changes to lots and lots of items.

Parameters:

• fn - The function to be executed upon the initialization of a prefab.

Examples:

Spoiler

AddPrefabPostInitAny(function(inst)
	print(“I am LITERALLY EVERYTHING, WAHOO!”)
    	--Code here is applied to EVERY prefab in the game (That includes modded prefabs too!)
end)

AddPrefabPostInitAny(function(inst)
	if GLOBAL.TheWorld.ismastersim then --This makes sure only the server side passes this check. Since components are server only it's important to do this else you risk memory leaks on the poor client!
		inst:AddComponent("edible") --Hell yeah, everything in the world is edible now
	end
end)

 

 

AddComponentPostInit

Spoiler

AddComponentPostInit(component, fn)

The AddComponentPostInit function lets you make changes to a component upon the initialization of it. It is extremely important to know that AddComponentPostInit will NOT let you make changes to replica components(Components replicated to the client side to pass information from the server to client). For replica components you'll need to use the AddClassPostConstruct function.

If you're unsure what components are and how they work, then be sure to check out my post on components!

All the components in the vanilla game can be found in the scripts/components folder.

Parameters:

• components - The name of the component you would like to edit
• fn - The function to be executed upon the initialization of this component.

Examples:

Spoiler

AddComponentPostInit(“locomotor”, function(self)
	print(“I have got locomotion!”)
	--Code is applied to the component you're editing
end)

AddComponentPostInit("combat", function(self)
	self.test = 30
end)

--Every entity with the combat component added will also have the test variable attached to the component. With this postinit I can now access test through inst.components.combat.test and use/change it how i'd like.

 

 

 

AddBrainPostInit

Spoiler

AddBrainPostInit(brain, fn)

The AddBrainPostInit function lets you make changes to brains upon their initialization. All of the brains can be found in the scripts/brains folder

Parameters:

• brain - The name of the brain file you'd like to edit.
• fn - The function to be executed upon the initialization of this brain.

Examples:

Spoiler

AddBrainPostInit(“pigbrain”, function(self)
	print(“I am the hilarious pig, oink oink”)
        --Code is applied to the brain you're editing
end)

 

 

 

AddStategraphPostInit

Spoiler

AddStategraphPostInit(stategraph, fn)

The AddStategraphPostInit function lets you make changes to stategraphs. All of the stategraphs can be found in the scripts/stategraphs folder.

Parameters:

• stategraph - The name of the stategraph you'd to edit.
• fn - The function to be executed upon the initialization of this stategraph

Examples:

Spoiler

AddStategraphPostInit(“oceanfish”, function(self)
	print(“this is the stategraph for the ocean fish!”)
    	--Code here is applied to the stategraph you're editing
    
    --States, eventhandlers and actionhandlers associated with this stategraph can be accessed with self.states, self.events, and self.actionhandlers
end)

 

 

 

AddCookerRecipe

Spoiler

AddCookerRecipe(cooker, recipe)

The AddCookerRecipe function lets you add custom recipes to crockpots.

Parameters:

• cooker - The prefab name of the crockpot you're adding the recipe to
• recipe - A table containing your recipe data. Be sure to check out scripts/preparedfoods.lua to see how recipe data is constructed.

Examples:

Spoiler

local customrecipes = require(“preparedfoods_custom”)

for k, v in pairs(customrecipes) do --A table loop to add all the returned recipes from the preparedfoods_custom file to the Crockpot and Warly's Portable Crockpot
 	AddCookerRecipe(“cookpot”, v)
	AddCookerRecipe(“portablecookpot”, v)
end

 

 

 

AddIngredientValues

Spoiler

AddIngredientValues(names, tags, cancook, candry)

The AddIngredientValues function lets you add ingredient values to your ingredients. Any prefabs that get any added ingredient values will then be able to be put into crockpots.

I suggest taking a look at scripts/cooking.lua to see more examples of this function.

Parameters:

• names - A table containing a list of prefab names of which the tags will be added to
• tags - A table of tags associated with the prefabs in the first parameter. These tags determine what recipes can be made with these ingredients. To see which cooking tags exist in the game take a look at the scripts/cooking.lua file.
• cancook - A boolean determining if the prefabs in names can be cooked on a fire pit.
• candry - A boolean determining if the prefabs in names can be dried on drying racks.

Examples:

Spoiler

local fruits = {"pomegranate", "dragonfruit", "cave_banana"}
AddIngredientValues(fruits, {fruit=1}, true)

 

 

 

AddRecipe

Spoiler

AddRecipe(name, ingredients, tab, level, placer_or_more_data, min_spacing, nounlock, numtogive, builder_tag, atlas, image, testfn, product, build_mode, build_distance)

The AddRecipe function lets you add custom recipes for an entity in the game.

Be sure to take a look at scripts/recipes.lua for examples on how AddRecipe is used.

Parameters:

• name - The name of your recipe (The game will set the product of the recipe to be the name of it if you don't set a custom product yourself)
• ingredients - The ingredients required for this recipe.
• tab - The crafting tab this recipe is in
• level - The tech required for the user to be able to craft this recipe
•  

Examples:

Spoiler

AddRecipe("blowdart_explosive", {Ingredient("cutreeds", 2), Ingredient("nitre", 1),Ingredient("feather_robin", 1)}, RECIPETABS.WAR, TECH.SCIENCE_ONE)

 

 

 

AddRecipeTab

Spoiler

AddRecipeTab(rec_str, rec_sort, rec_atlas, rec_icon, rec_owner_tag, rec_crafting_station)

The AddRecipeTab function lets you create your own custom recipe tabs to the game.

Be sure to check out scripts/constants.lua and look for the RECIPETABS and CUSTOM_RECIPETABS variables for examples on recipe tabs in the game.

Parameters:

• rec_str - The tooltip string associated with your custom crafting thing
• rec_sort - Determines the position of your tab in the crafting tab list. The higher the number the lower it appears on the list.
• rec_atlas - The path to the atlas containing the data for the image associated with this tab
• rec_icon - The path to the texture containing the image associated with this tab
• rec_owner_tag - The tag the character requires to access this crafting tab. This can be left as nil if your crafting tab is not character exclusive.

Examples:

Spoiler

local tinkeringtab = AddRecipeTab("Tinkering", 999, "images/tinkeringtab.xml", "tinkeringtab.tex", "tinkerer")

 

 

 

RemapSoundEvent

Spoiler

RemapSoundEvent(name, new_name)

The RemapSoundEvent function lets you override old sound paths with new sound paths. This is very useful if you’d like to replace a certain sound in the game.

Parameters:

• name - The path to the sound you are overriding.
• new_name - The path to the sound you are overriding the first path with.

Examples:

Spoiler

RemapSoundEvent("dontstarve/rabbit/scream", "customsounds/rabbit/scream_new")

 

 

 

AddReplicableComponent

Spoiler

AddReplicableComponent(name)

The AddReplicaComponent lets you add new replicable components to the game. Replica components are used for passing information from the server to the client. To add a replicable component you must have your replica file put in the components folder, and name it to “componentname_replica”(Replace componentname with whatever component you are adding a replica of). Then you may call the AddReplicableComponent function like this

AddReplicableComponent(“componentname”)

And the game will automatically add the replica of the component to the client when the component is added to the server side.

Parameters:

• name - The component you are adding a replica of.

Examples:

Spoiler

AddReplicableComponent(“hunger”) --Adds a replica for the hunger component

 

 

 

RegisterInventoryItemAtlas

Spoiler

RegisterInventoryItemAtlas(atlas, name)

The RegisterInventoryItemAtlas function can be used to add an item's inventory icon and atlas to a global lookup table. Anywhere that calls GetInventoryItemAtlas will use this table for the item you added the inventory icon for.

This is to make sure your items icon will appear in the inventory, or in the crafting recipes, cookbook or anywhere else, without having to cover each one seperately.

Parameters:

• atlas - The path to the atlas associated with your image
• name - The name of the texture associated with your image

Examples:

Spoiler

RegisterInventoryItemAtlas(“images/inventoryimages.xml”, “acorn.tex”)

 

 

 

AddMinimapAtlas

Spoiler

AddMinimapAtlas(atlas)

The AddMinimapAtlas function is used to add new xml’s for minimap images to use.

Parameters:

• atlas - The path to the atlas you'd like to make available as a minimap image.

Examples:

Spoiler

AddMinimapAtlas("images/minimap/babydragon.xml") --Images defined in the xml can now be used as minimap images

 

 

 

RemoveDefaultCharacter

Spoiler

RemoveDefaultCharacter(name)

The RemoveDefaultCharacter can be used to remove vanilla characters from the character select screen.

Parameters:

• name - The prefab name of the character you'd like to remove from the character select screen.

Examples:

Spoiler

RemoveDefaultCharacter(“wilson”) --Removes wilson as a choosable character

 

 

 

Edited January 29, 2022 by Hornete
Added more and edited

[amoryleaf]

This is amazing. Thanks so much. I just started my modding journey and your posts are a godsend 

[ScrewdriverLad]

On 2/16/2021 at 8:03 PM, Hornete said:

AddCookerRecipe

okay, so I just implemented a new crock pot meal but it's not appearing in the crock pot. I know that the item appears on the ground and in the inventory, but not in the crock pot. Any ideas what to do?

[ClumsyPenny]

RegisterInventoryItemAtlas just won't work for me, I put it in modmain and it does nothing. I tried putting it after the Assets and also after the Prefabs. No crash, nothing in the client_log that I can tell.

 RegisterInventoryItemAtlas("images/inventory/recycle_inv.xml", "recyclescrap.tex")

This is what I'm doing, I'm sure the Atlas and Image name are correct, I was using them already to manually assign the image where relevant (inventory image, recipe ingredient, etc.), but then I found out about this method which would be less tedious and make Mini Signs work. I also tried going with the Prefab name instead (the same minus the .tex), which is what a comment in modutil recommends, but still nothing.

[Wonderlarr]

On 2/21/2022 at 8:58 PM, HobNob said:

RegisterInventoryItemAtlas just won't work for me, I put it in modmain and it does nothing. I tried putting it after the Assets and also after the Prefabs. No crash, nothing in the client_log that I can tell.

 RegisterInventoryItemAtlas("images/inventory/recycle_inv.xml", "recyclescrap.tex")

This is what I'm doing, I'm sure the Atlas and Image name are correct, I was using them already to manually assign the image where relevant (inventory image, recipe ingredient, etc.), but then I found out about this method which would be less tedious and make Mini Signs work. I also tried going with the Prefab name instead (the same minus the .tex), which is what a comment in modutil recommends, but still nothing.

You still need to declare the used assets in your assets table, you're doing that correct?

 

[ClumsyPenny]

9 hours ago, TheSkylarr said:

You still need to declare the used assets in your assets table, you're doing that correct?

Yes, absolutely, they're declared in modmain above where I'm trying to use RegisterInventoryItemAtlas. I'm also using those same assets elsewhere so I'm sure they work.

[Digi_056]

not 100% sure if this is your problem but RegisterInventoryItemAtlas had some weird quotation marks when I copied it

with normal quotation marks

[SinnyDeas]

Quote

AddPopup

--”player” is the player you’d like to activate the popup for
player:ShowPopup(POPUPS.YOURPOPUPID, true) --set to true for popup to show up, set to false for pop up to go away

The 'u' in ShowPopup is uppercase for me. ShowPopup => ShowPopUp.

I was getting low on sanity with the "a nil value" error