How to Create Hatching Spider Eggs

In this how-to we’ll take a look at how we can create spider eggs which, when destroyed, spawn a spider. With this tutorial we’ll get to know how scripting hooks work in practice and how to pass parameters to functions in other script entities. I hope you’re prepared to take your scripting skills to the next level!

First, let’s create a clone of the spider eggs asset by adding this to the objects.lua under your custom dungeon’s “mod_assets\scripts” folder with a text editor:

cloneObject{
	name = "spider_eggs_hatching",
	baseObject = "spider_eggs",
	onDie = function(object)
		eggScript.breakEggs(object.level, object.x, object.y)
	end,
}

We clone a new asset based on the old spider eggs and add a new function into its onDie scripting hook (for all the hooks, see the asset definition reference). Scripting hooks can be used to run any Lua script when a certain event happens (in this case when the eggs break) and it can be used in creating customized item and prop functionality or even altered monster behavior.

We could implement the whole script here but to make iterating the script faster, we’re going to refer to a script in the dungeon instead: to refresh the changes from objects.lua, the project needs to be reloaded whereas script entities in the dungeon can be instantly refreshed. To do this, we refer to a function called breakEggs in an script entity with the ID of eggScript. We also pass a few parameters to the function: the level and coordinates of the object being killed so that we can spawn the spider into the correct location.

This was just the first half of the work. To get the rest of it up and running, we now need to switch back to the dungeon editor (but remember to save the objects.lua and reopen the project in the dungeon editor!). Let’s start off by adding a few of our new spider_eggs_hatching entities to the map, as well as a script_entity whose ID we set to eggScript. Into this script entity, we will implement what actually happens when the eggs are smashed:

function breakEggs(level, x, y)
	local facing = (party.facing + 2)%4
	spawn("spider", level, x, y, facing)
end

It’s a pretty short and simple script since we essentially need to do one thing only: to spawn a spider where the eggs were. To get the spider to the correct location, we use the parameters we passed from the onDie-hook in the spawn command. To spice it up a little, we also set his facing parameter to always automatically face the player by using a small math trick: the facing values go from 0 (north) to 3 (west) so by adding 2 to the facing of the player party, we can essentially rotate the spider by 180 degrees. After the addition the range of the numbers is 2…5 so we use modulo (the % operator) to put the values back into the range of 0…3.

This script will print a warning on console about an invalid spawn location when the eggs are broken. This is due to the fact that the onDie event happens right before the eggs are destroyed (since the event needs to be able to also prevent the object from being destroyed if necessary) so the spiders are very briefly on top of the eggs. However, we know that the eggs will be gone so we know the overlapping entities won’t cause any problems and thus we can safely ignore the warning.

And there you have it: actual working spider eggs that hatch. It’s easy to take this script and adapt it into, for example, a stack of barrels and crates (barrel_crate_block) from where you could find some randomized loot with increasingly rare items found on lower floors by referring to the level parameter of the object.