This guide is a direct continuation to Modding Pt.1: Custom Microgames and Modding Pt.2: Custom Boss Stages. It is strongly recommended that you read them first, as we will not be repeating what we learned in previous parts.

In this part, we will learn how to make a custom level that we created be loadable from within the Extras -> Scenes menu in the main menu, kind of like the Sandbox. We will also learn how to attach scripts to that level to run our own exclusive gamemodes.

As an example, we will make a simple deathmatch scene called "Kai Wars", where players battle each other and gain score for frags. When a player reaches the score threshold, they will win and the scene will restart. We'll also scatter BONUS DUCKS because we just need to have ducks in this tutorial too.

The sources and assets for this scene can be found in this Google Drive folder.[drive.google.com]

Let's get to it!

In the previous part, we learned how to create custom levels with MicroKit. For this scene, I've prepared a simple little playground where players will battle each other:



You can create your own level, or get this one from the Google Drive folder.

Once you've prepared your geometry, import it into MicroKit and create your level.



Looking good! Let's fill up some entities, like the spawn points and weapon spawners.



Ready? Let's save the level into:


And that's it! Our level is ready to be played. If you want to skip over the level creation part and just want to learn how to create the scene, you can always grab the final level from the Google Drive folder.

Now that we have our level, let's learn how to create a scene that will load into this level.

You probably have an idea of how this is gonna go. Let's navigate to StreamingAssets, and create a new "Scenes" folder.

Inside that folder, we'll create a .scn file, which will be the scene descriptor. Like .mcg and .bos, .scn is a json file in disguise, but it might have some slightly different rules compared to those other two descriptors. It looks something like this:

PAY SPECIAL ATTENTION: Unlike the other two descriptors, paths defined in a scene descriptor use the "Scenes" (StreamingAssets/Scenes) folder as the root. So for example, if my thumbnail texture lies in:


I will define it in the descriptor as:


* SceneName: The name of the scene. If you have a localization file supplied, you can pass the key of the localization entry. If no key is found in the localization corresponding to what you provided, it will use your value as is.

* SceneDescription: The description of the scene. If you have a localization file supplied, you can pass the key of the localization entry. If no key is found in the localization corresponding to what you provided, it will use your value as is.

* SceneGamemode: The gamemode to start the scene in. This usually has no special effect because the coordinator won't run, but it might be useful in specific cases, like if you want to enable team splitting in your scene. Valid inputs are:

- Pointmatch
- TeamPointmatch
- Scorematch
- TeamScorematch
- Survival
- LastPlayerStanding
- LastTeamStanding
- BossRush
- TeamBossRush

* SceneThumbnail: Path to the scene thumbnail in .png format. The aspect ratio should be 16:9.

* SceneOnlineModes: An array of strings that define available hosting options. Valid inputs are:

- Public
- FriendsOnly
- SinglePlayer

* SceneLocalization: Object table that define paths to localization files for each language code. Here's what my "en" localization file looks like:


* SceneLevels: An array of tables that define a level. You can set up multiple levels in one scene, and it will load one at random.

Each entry table must contain two keys: "NameMustMatchInFull" (bool) and "Name" (string).

"Name", of course, defines the name of the level. "NameMustMatchInFull" defines whether to search for one specific level named exactly as provided, or whether to gather all levels that contain the provided name. For example, if I want my scene to load every custom level that starts with "kw_" I will make the entry like so:


This is useful if you want to make a specific gamemode that requires specific custom maps, and also allows other users to create maps for this gamemode you created.

* SessionVariables: Another array of tables that define a session variable. Session variables are variables that persist for as long the game is running, and don't get reset between level changes. This is useful, for example, if you want to create a script that will run on any level (through AutoRun), but will only activate if the right session variable has been set. Like a gamemode that can run on any level but must be activated from the scene.

SessionVariables are defined like so in the scene:


And you get them from script with:


Remember that you can always generate this file through MicroKit as well.



We now have an easy and accessible way of loading our custom level. This on its own can be nice, allowing you to make sandbox type levels that you can chill out with your friends in. But what if you want more? What if we want to turn this level into a game?

Let's learn how to load code from a level.

Making a lua script execute when you load your level is incredibly simple. First, you have to navigate to where your custom level is saved (the .lua file generated by MicroKit).

When you open that file, you'll notice it returns a lot of parameters, which is what MicroWorks processes. We're going to add a new parameter inside that return table, called "lua".

This lua parameter will be a table with a list of paths to each lua script you want to run when this level loads. Like the scene descriptor, the paths defined in the level descriptor take the level folder as the root, so if I will put my script inside:


In code, the path will be:


So, anywhere inside the .lua descriptor, add the following:


And that's it! Now when your level loads, the lua file specified in the path will execute. Let's create this file now, and write some game code.

The premise is very simple: When a player dies, the host will check who killed that player, and award them score. If they reached the score limit, they will be declared winners, and the level will restart.

Let's start with variables:


Let's create the function that will be called when a player should get awarded score. Most of the code should be self explanatory to you by now (you've grown up so fast.....)


After that, we add the "PlayerDied" listener.


Let's also add a listener to "PlayerSpawned", and check if the player that spawned was us. If that player was us, we'll make the health UI appear.

We have to do this on every spawn because the health UI hides itself when you die.


And then at the very end: A function that will handle actually starting the gamemode. We will first clear everyone's score, because score persists between levels.

Then, we will enable the microgame HUD, and customize some stuff. We will call this start function as soon as we define it.




I've added an icon texture to set as the round counter icon, and defined it at the beginning variables:


That's it! It's that simple. You can now launch your level and invite your friends for some Kai Wars action.


if only i had friends...

I promised you there would be ducks! Before we wrap everything up, let's do one final little duck script for good old times' sake.

Every random amount of time, we will spawn a duck at the center of the map that will hover and spin in the air. When a player uses the duck, they will gain bonus points.

Let's open up MicroKit again and load our level. I'll import the same duck model we've used in the microgame part of this tutorial series, and place it at the middle point, hovering above the air.

I'll also make sure to expose it to lua, and call it "BonusDuckModel". I'll also disable collision on the duck, and only make use of the player trigger we will add to it.

Finally, I will add an audio source in the same position, that will play when the duck is picked up. Of course, expose it to lua and call it "BonusDuckSound".



BEFORE YOU SAVE THE LEVEL: Keep in mind that this will erase the "lua" table we've added earlier into the level descriptor. Copy that table before you save, so you can paste it back in after you save.

With our level updated, let's return to the code, and define new variables for the bonus duck:


The only things the host will sync is when the duck spawns, and when the duck is picked up. Other than those two, the host will keep track of who picked up the duck and when to spawn it.

Let's make two new functions: SpawnDuck() and HideDuck(). Make sure you specify the new duck functions after the "AddScore" function.


And then, define the Server -> Client RPC's that will call these functions on the clients:


Now let's add a function for when the duck is picked up. Only the host will be aware of who picks up the duck, so this function will be host only:


Finally, all that's left is a function to set up the duck. We will call this function at the end, together with "StartKaiWars()".


And now we have a magic duck item that gives us points when we grab it!

So, to summarize, in order to make a scene, we:

1. Add a scene descriptor (.scn) into StreamingAssets/Scenes
   
   
2. We specify the scene data, including the levels it can load and the scene menu assets.
   
   
3. To make a custom level load a script, we will define the path to it in the level descriptor.

Congratulations on making it... TO THE END! In this part, we learned how to create custom scenes, and how to load scripts in custom levels.

First of all, if you've made it all the way here, I bow before you. This is no quick & easy tutorial, and if you've made it this far, it sounds like you've made it. Congrats!

You should now have a full understanding of scripting in MicroWorks, and the power to create almost any microgame or boss stage you desire. You can even just make any level or gamemode you want!

We hope you've found the guide useful and intuitive, and we can't wait to see what you bring out to the workshop. We'll be watching!

Remember to join our Discord[discord.gg] server if you wish to connect with other modders or with the devs (hi!), we'll be more than happy to help you with any query.

Until next time!