Hosting a scripting enabled server requires the Party Pass DLC. If you don't already own it, you will have to get it.

https://steamproxy.net/steamstore/app/2355460/MicroWorks__Party_Pass/

Lua is the scripting language that powers custom scripts in MicroWorks.

Whether it's microgames, boss stages, or an AutoRun script, you'll fare far better if you're coming into this with a basic understanding of the Lua language. https://www.lua.org/

Y'know, something to write the Lua code in (that isn't notepad).

Some recmomendations: Visual Studio Code[code.visualstudio.com], Sublime Text[www.sublimetext.com], or even the lightweight Notepad++.[notepad-plus-plus.org]

Not planning to walk in blindly, are you?

The MicroWorks Scripting Documentation details all exposed functions and events that you can make use of in your scripts. You'll want to have it opened in a tab while you're working: https://agiriko.digital/docs/

MicroKit is the official MicroWorks modding toolkit.

It will allow you to create custom levels (especially necessary later on for boss stages), convert assets to the MicroWorks format, pack and upload mods, and more.

You can find it in your Steam tools library, under MicroKit - MicroWorks Editor.



In this Google Drive folder[drive.google.com], we've compiled some useful resources for your modding ventures, including helper scripts, mod examples, and the assets of the final results of this very guide you're reading.

If you're here mostly to learn, and less waste time on assets, you can always download the assets provided in that folder, "Tutorial Results". (for example, microgames require music, so you can grab the music provided in that folder. Music that, by the way, was specially created for this guide by my insanely talented friends Musearys and Tyra!)

I'd also like to bring attention to the Raycast Debugger script in Helper Scripts/Raycast Debugger. This script will display world coordinates at the position that your crosshair is aiming at, and can be very useful if you need to know the specific position of a point in the map, especially when you're making custom microgames and want to spawn something in the Nexus.

Before we jump into the meat and juice of this guide, it is important to understand the scripting interface and documentation correctly.

First, let's navigate to Steam/steamapps/common/MicroWorks/MicroWorks_Data/StreamingAssets.

This is the root of where files will be read from, and where you'll be working from most of the time. When specifying paths to files in the code, you're gonna want to treat this as the root folder. So for example:

If I want to load a texture in:

I will specify the path in the code as:

In StreamingAssets, let's create a folder called "Scripts", and inside that folder, create another folder called "AutoRun". Scripts located inside "StreamingAssets/Scripts/AutoRun" will automatically execute when a level loads, if the server has scripting enabled. This can be used to make global mods like the UT Announcer or the Kill Feed.

Inside the AutoRun folder, let's create a "TestScript.lua" file, and start editing it. We'll use this file to test out the numerous examples we're about to learn from the documentation. Speaking of the documentation, let's avert our attention there for a moment and start to analyze it...

Let's have a look at the documentation.[agiriko.digital]

General is the category for generalized interfaces that don't always necessarily lend themselves to an asset or entity. Most notable entries from the general category are Global and WorldInfo.

* Global[agiriko.digital] is the global-scoped class that contains functions that are baked into the Lua sandbox, and can be freely called as-is.

For example, the following function will try to load a texture from a specified path:


As you can see, FileExists and LoadResource are both functions from the Global sandbox.

* WorldInfo[agiriko.digital] is the class that facilitates the connection between Lua and the MicroWorks world. It usually contains functions pertaining to the game world or active server.

Functions from WorldInfo are called via: worldInfo:Function(). For example:


Very often, you may want to create delayed execution, like calling a function and then waiting some time before calling another function. This is where RunAsync can help.

RunAsync is a wrapper for a function that allows inserting awaiters. For example:


This will make the script wait 5 seconds before displaying the message.

There are many awaiters that you can find in the Global[agiriko.digital] class. Some examples are:

* Yield() - Waits a single frame.
* Wait(Frames(5)) - Waits 5 frames.
* Wait(Seconds(5)) - Waits 5 seconds.
* Wait(Until(function() return worldInfo:GetSynchronizedTime() > 60 end)) - Waits until the provided function returns true. In this instance, it will wait until the time since the game started has passed a minute.
* Wait(Event("PlayerJoined")) - Waits until the "PlayerJoined" event fires. More about events later.

Keep in mind that just like the name implies, RunAsync runs asynchronously, meaning that the code written inside will run in its own separate routine, and the code written after the RunAsync will continue to run normally.

Types are additional value types to the ones you may already be familiar with (booleans, floats, strings, etc).

For example, LuaVector3[agiriko.digital] is a vector holding 3 float values, that can be created via Vector3(x,y,z).

Usage example:


Other notable types are:

* LuaColor[agiriko.digital] - Color(x, y, z, w)
Constructs a Color with 4 provided floats for RGBA values, of 0-1 range.

* LuaQuaternion[agiriko.digital] - Quaternion(x, y, z, w)
Constructs a Quaternion with 4 provided floats. Please do EulerToQuaternion(Vector3(x, y, z)) instead to get a rotation from euler angles. It is not recommended to construct quaternions yourself, unless you understand them inside-out.

Resources are assets that you load from the disk via LoadResource(Path, ResourceType), where ResourceType can be:

* ResourceType.Texture[agiriko.digital] (.png, .jpg)
* ResourceType.Audio[agiriko.digital] (.ogg)
* ResourceType.MemoryAudio[agiriko.digital] (same as ResourceType.Audio, but allows the sound to be reused across multiple sources)
* ResourceType.Model[agiriko.digital] (.nmd, requires MicroKit to create)
* ResourceType.Skybox[agiriko.digital] (.png, .jpg, will create a cubemap out of the provided image)
* ResourceType.Text (Any file, will read and return its contents as a string)
* ResourceType.Bytes (Any file, will read and return its contents as an array of bytes)

Example usage can be:

Wrappers are interfaces for the many entities and classes MicroWorks has.

For example, if you get the local player via worldInfo:GetLocalPlayer(), we can see in the documentation that it returns PlayerControllerWrapper[agiriko.digital], and we can use the functions available for us in the documentation for that wrapper.

It's very important to note that wrappers are, as their name implies, just a wrapper for the entity, allowing you to call functions for that entity, but are not a direct reference to the entity. That means, for example, if you want to check whether the entity has been destroyed, doing "wrapper ~= nil" is wrong, because the wrapper will persist even after the object's death. Instead, you want to use "ObjectExists(wrapper)", like so:


As an exercise, let's make a function that, when called, will award the host with a special weapon, and everyone else with a different weapon.


Now, let's say I want to spawn an entity, like an audio source. WorldInfo contains the "CreateEntity(EntityType)" function, where EntityType can be:

* Entity.UIImage[agiriko.digital] - creates a UI image.
* Entity.UIText[agiriko.digital] - creates a UI text.
* Entity.Decal[agiriko.digital] - creates a decal.
* Entity.PointLight[agiriko.digital] - creates a light.
* Entity.ReflectionProbe[agiriko.digital] - creates a reflection probe.
* Entity.AudioSource[agiriko.digital] - creates an audio source.
* Entity.Trigger[agiriko.digital] - creates a trigger field.
* Entity.Killer[agiriko.digital] - creates a killer field.
* Entity.Bouncer[agiriko.digital] - creates a bouncer.
* Entity.Teleporter[agiriko.digital] - creates a teleporter.

After creating an audio source, I want to move it to a desired location. Moving objects around requires them to have a Transform[agiriko.digital], and so long as they inherit from Component[agiriko.digital], you should be able to call :GetTransform() to get their transform and manipulate it.

You can check what each wrapper inherits from in the documentation. For example, in the AudioSourceWrapper, we see the following header:

"public class AudioSourceWrapper : MonoBehaviourWrapper".

This means that it inherits from MonoBehaviourWrapper. MonoBehaviourWrapper, in turn, inherits from ComponentWrapper, which contains the "GetTransform()" function we need. Great!

So, in code we'd do:


In addition to the transform, objects derived from ComponentWrapper will also give you access to :GetGameObject() (GameObjectWrapper).[agiriko.digital] The game object is an object in the world that can have any component attached to it. For example, the audio source we created is actually just a component attached to a game object. So, every component has a GameObject, and every component has a Transform.

The game object contains many useful functions that you can use on all entities, such as SetActive(), or Destroy(), or even MakeUsable() and ListenToCollisions() (given this gameobject has collision, most notably for models).

* When spawning a UI object such as a UIImage or UIText, use :GetRectTransform() instead of :GetTransform(). More about UI in Part 2.

Events are notifications that fire when a specific event happens. For example, when a player joins the server, a "PlayerJoinedEvent" will fire.

We can listen to these events, attach code to execute when they happen, and even get information about them, like the player that joined in "PlayerJoinedEvent".


The functions that we can use on the payload (pay) vary on each event, and are detailed in the documentation.

Another example could be:

MicroWorks is a multiplayer game, and so you need to understand client-server relations and how each function you call will affect the online state of the game.

In the documentation, you will see that the description for each function starts with the following:

* (Server)
* (Client)
* (Client/Server)

(Server) indicates that the function is already synced by the game, and should only be called from the host. Trying to call it from a client could lead to an error at best and stuff breaking at worst.

If the function returns information (is not void), it likely means only the server is updated on this information and clients may not be up-to-date. In this case, it may be up to you to manually sync it.

(Client) indicates the function is not synced, and although it can safely be called from anyone, it will only execute locally. If you need to sync it, you will have to do so manually.

If the function returns information (is not void), it likely means all clients are already up to date on this information and no additional syncing is required (given that no local changes were made to it from script).

(Client/Server) indicates that the function is already synced by the game, but can still be safely called from either server or client (given that the client has authority to perform this action).

For example, PlayerController:Kill() is marked as (Client/Server). This means if we call it on ourselves, we will update the server and the server will sync it. If the server calls it on us, it is also valid. If we try to call it on another player, that will not work.

If the function returns information (is not void), it likely means all clients are already up to date on this information and no additional syncing is required (given that no local changes were made to it from script).

Now that we understand what's synced and what's not, we need to understand how to sync stuff ourselves.

That's where Remote Procedure Calls (RPCs) come into play. They are essentially just messages to a server or a client that say "Hey, please execute this function!".

RPCs are set up like so:


This will create the RPC and store it into the worldGlobals global table that's shared across all scripts. Once created, you can call worldGlobals.RPCName() to execute it.

There are 4 parameters that you supply to the RPC:

1. Name - The name as a string.

2. SendTo - From where to where should this RPC get sent? Valid options are:

* SendTo.Multicast - Sent from the host to everyone in the server (including the host).
* SendTo.Server - Sent from the client to the host.
* SendTo.TargetClient - Sent from host to a specific client.

When an RPC is set as TargetClient, the first parameter you supply to worldGlobals.RPCName() should be the PlayerController you wish to send this message to.

It is important to verify that the RPC is being called from where it's supposed to. For example, you don't want to call a multicast RPC from a client.

3. Delivery - What protocol to send this message over? Valid options are:

* Delivery.Reliable - Will ensure the message gets delivered and in order, but could take slightly longer. Use this if you can't afford the message to get lost or arrive out of order.
* Delivery.Unreliable - Will fire and forget, meaning that if the message didn't make it to the other side, it is lost forever. Use this if you absolutely need speed and can afford to lose a few packets.

4. Function - the code to execute.


Here's an example of how we can use RPCs to sync information from the host to the clients:


Or, in a more advanced example of Target Client RPC, where we'll update every joining player with a random number we picked at the beginning of the level:

Now that we understand how to script in MicroWorks, we can do what we all came here for: microgames!

For this tutorial, we're gonna make a microgame called "Pop the Duck". In this microgame, players have to work together to inflate a rubber duck until it pops. If they succeed, everyone wins.

The host will keep track of the duck state and sync it to clients (where to spawn the duck, how many inflations it will require, etc etc). When clients inflate the duck, they will inform the server who will decide on the current size of the duck and pop it when it is big enough.

Let's return to StreamingAssets and delete the AutoRun scripts we've created. Instead, we're going to make a folder called "Microgames".

This is the folder where custom microgames are loaded from (StreamingAssets/Microgames). To create a microgame, we need to add a .mcg file to the folder.

Despite the extension, .mcg files are just .json files, and they contain information about the microgame we want to make. That information being:

* Title - The internal microgame name. This will be used for localization.
* Author - Name of the microgame author.
* Launch - Path to the lua file to execute when this microgame is enabled.
* Difficulty - Difficulty level of the microgame. 1 for Easy, 2 for Medium, 3 for Hard.
* MinPlayers - Amount of players required to run this microgame.
* I18n - Paths to localization files. Key is the locale code, and value is the locale path.

You can either generate this file with MicroKit (File -> New -> Microgame), or you can create it yourself:


As you can see, you can even define multiple microgames in one file. But for now, we'll keep it at just one.

Let's create the files we've specified.
First, the .lua script (Microgames/PopTheDuck/PopTheDuck.lua),
And then the .json file (Microgames/PopTheDuck/Locale/en.json).

Before we begin work on our code, we have to prepare all the assets for this microgame, starting with the localization.

Localization, too, is provided in .json format. You can create it manually, or in MicroKit (File -> New -> Locale). Full localization guide available here.

You can add any localization strings your microgame may require, but it must contain two important entries: the display name and the instruction name.

The display name is the name that will appear in menus and other UI elements, like the mutators or game details. The key of it in the localization must be "Microgame_NAME_BaseName", where "NAME" is the internal name you specified.

The instruction name is the name that will appear in the actual in-game UI, when you receive the instruction. The instruction name can have multiple localization entries for different variations, which you will also define in the lua script, but it must always have the "default" variation as, well, the default.

The key of it is "NAME_VARIATION", where "NAME" is the microgame name you will define in the lua script, and "VARIATION" is the name of the variation that you will also define in the lua script.

Here's the localization file I've created for Pop the Duck:

Before we head into the code, we have to prepare all the assets we will need for this microgame.

The first and most important thing that every microgame needs is the music. You will have to prepare 6 tracks in .ogg format, with each track corresponding to each speed level. (did you know that with mutators, you can turn up the speed to x6?)

The length of the microgame is determined by the music track. If your music track is 5.5 seconds long, the microgame will last 5.5 seconds. In MicroWorks, we speed up the track on each level by 11%.



* _100 for x1
* _111 for x2
* _122 for x3
* _133 for x4
* _144 for x5
* _155 for x6

After we've gotten our music ready, we can start preparing the assets specific to the microgame we're making. Let's prepare feedback sounds for when we inflate the duck and when the duck pops.

I created the "DuckInflate.ogg" and "DuckPop.ogg" sounds, and placed them inside "Microgames/PopTheDuck/Sounds".

If you're not particularly great with audio, you can grab the sounds from the finished results folder in the google drive link provided at the beginning of this guide.

Remember that sounds must be of type .ogg. MicroWorks currently does not support other sound types.

Now let's focus on the star of the show: The rubber duck 3D model. I got this cute rubber duck model from Ikki_3d on Sketchfab[sketchfab.com], and imported it into a 3D software like Blender, so I can adjust the position and scaling, and later export to .obj - the file format we will need.

A few more touches here and there, and Jason the Duck is ready to go!



Let's export him to .obj into a temporary folder, and launch MicroKit - so we can convert him into a model format that MicroWorks accepts (.nmd).

Inside MicroKit, head over to the menu bar at the top and navigate to File -> New -> Level. We'll be learning more about level creation in the next part, but for now, we are only interested in exporting Jason.

At the asset browser tab at the bottom, press "Load Asset" and navigate to your model.



Let's preview him inside the level by pressing "Add Entity" at the entity list on the left, and selecting "Model". In the inspector tab on the right, you will see the "Model" category and a "Model" parameter. Simply drag the loaded asset icon into that parameter, and the model will be assigned to the entity!



This will help us visualize the pivot or the scale of the model next to the player character. Unfortunately, MicroKit can't edit the source model - if you need to adjust the scaling, you will have to go back into Blender or your 3D editor of choice, adjust the scaling, and re-import the model.

Fortunately, you can use the transform properties to scale the model in the editor to see how much you'll need to scale it in the 3D editor! But don't be confused - editing the transform values will not reflect on the exported model. They are only reflected on world entities.



Now the last part is just editing the materials - select your imported asset in the asset browser, and head over to the inspector on the right again. You can set whether this model should have collision enabled (for our case, we want to keep it on), and then press on "Edit Materials".

A new window will open with all the materials of your model. From here, you can upload textures and mess with parameters until you're satisfied with your model's look.



Jason looks great! Let's export him.

Go back once more to the asset browser, and this time right click on your imported asset. Click on "Export Asset", and select the folder to export to. In my case, I'll already export it directly to the microgame folder, inside:


This will generate 3 files:

* .nmd - The model descriptor. This is the file you pass when you want to load a model in code.
* .nmf - The mesh information.
* .nmt - The material information.

In addition, a "Textures" folder will also generate with all your model's textures. Make sure that folder is included in the same place as the .nmd file, and that if you decide to rename it for some reason, you reflect the change in the .nmd file.

With all assets at hand, we can proceed to the microgame code. Let's open up the .lua file we've created earlier and understand how to register a microgame.

To register a microgame, all you essentially have to do is call two functions from the Global scope:

* CreateMicrogameVariation
* CreateMicrogame

We will write the variations first, and create the microgame at the very end.

Variations can be multiple, and are basically different spins on the same microgame. For example, "Jump X Times" and "Crouch X Times" are variations of the same microgame.

Every time you call CreateMicrogameVariation, you're going to want to save the return value into a local variable. This is because when we call CreateMicrogame, we will need to pass a table that includes all the variations we've created.

Likewise, it might also be a good idea to save the return value from CreateMicrogame, as that will return LuaMicrogameWrapper[agiriko.digital], and you could potentially make use of the functions provided within it.

CreateMicrogameVariation takes 5 parameters:

* name - The name of the variation. This is used in the localization file you provided (for example, if I name my variation "Super", the localization key for it would be "PopTheDuck_Super").

If this is the default variation, and there has to be a default variation, you must name it "default", with a non-capital d.

* onBeginMicrogame - A function that will execute once when this variation starts.
* onMicrogameTick - A function that will execute on every frame that this variation is running.
* onPostMicrogame - A function that will execute once when this variation ends.

These 3 functions are always called on everyone (server and clients).

* rarity - (Optional) An integer number that determines how rare this variation is. The higher the value is, the more likely it is to appear. The default value is 8.

So, creating a microgame variation would look something like:


After you create all variations, you can create the microgame itself, with CreateMicrogame. It takes 4 parameters:

* name - The name of the microgame. This will be used in localization for the instruction display.
* musicArray - A table that holds the music for this microgame. It has to have 6 "AudioResource" elements.
* variationsArray - A table that holds all the variations for this microgame. Has to have at least 1 variation called "default".
* params - Extra data about this microgame, provided in a table. The elements are "Difficulty", "Rarity", "MinPlayers", "Type", "PlayEffect". Any of these elements can be left empty, as the function will auto fill them.

"Difficulty" is the overall difficulty of this microgame. Its values are: "Difficulty.Easy", "Difficulty.Medium", "Difficulty.Hard". Defaults to Easy.

"Rarity" is the rarity of the microgame. Same as with CreateMicrogameVariation.

"MinPlayers" is the minimum amount of players required for this microgame. Defaults to 1.

"Type" is the internal type of this microgame. This isn't used much, other than for a special round. Values are "MicrogameType.WinAtEnd", "MicrogameType.WinBeforeEnd", "MicrogameType.Versus", "MicrogameType.Coop". Defaults to WinBeforeEnd.

"PlayEffect" toggles whether we play the win effect right as the player is declared the winner by the coordinator. Defaults to false.

* If you're asking yourself "Didn't I already set these values in the microgame descriptor earlier?", the microgame descriptor's data is used for displaying in menus like the mutators or game details. The data you provide here will be used by the microgame coordinator. Nevertheless, the data between the two should match.

So, usage of this function would look like:

Now we understand how microgames work like, and with an understanding of scripting, we can focus on the logic.

Let's start by creating all the required variables and parameters for this microgame:


Next, we're going to create 3 functions that we will later pass to OnCreateMicrogameVariation.


Let's start filling it up! The bulk of our operations will happen inside OnBeginMicrogame(), so let's start there.

A worthy little side note and reminder - remember that lua is an interpreted language, meaning it is read from top to bottom, and trying to call a function before it was declared will result in an error. Be diligent and aware of how you structure and where you position your functions.



Right, where were we? Oh yeah, ducks. First order of business is to spawn the duck inside of OnBeginMicrogame():


Notice how I used the "GetRandomPointInNexusSynced" (that's a mouthful) function for the position. This function will return a random point in the nexus, but the beautiful thing about it is that everyone who calls it will get the same random position, without any syncing required. This is thanks to our Pseudo Random Number Generator (PRNG), that is re-seeded every time a new microgame starts, and that seed is automatically synced, meaning the random values returned can be pre-determined. Or, well, for your purposes, it's just an easy way to get a random value without having to do networking.

Anyway, on to the audio sources:


And now to set the duck's stats:


Finally, we will make the duck usable:


"GetI18n" is a function that fetches a value from the localization file, and you just have to supply the key to it. Remember how "Usable_Duck" was defined in the localization file we provided in the microgame descriptor?

We also add a listener to the "EntityUsed" event, and you'll notice we also provide "duckModel" after the function declaration. This means we are only listening to the event that has been fired from this object, rather than listening to *any* EntityUsed event that fires.

"OnDuckUsed()" is a function we have yet to declare and will do so soon. But let's just wrap up our beginning logic with:


As you can guess, "AddTargetIndicator" will add an on-screen indicator for the duck. Available IndicatorTypes are:

* IndicatorType.Objective
* IndicatorType.Warning

Indicators are automatically cleaned at the end of a microgame, so you don't need to worry about removing them. The same, however, cannot be said about hints.

"ShowHintWithGroup" will display a hint with the provided localization key. The "group" part is the name of a group that the hint belongs to. Hints will stop displaying if their group count has been marked as "seen" for more than the provided value in the function (by default 3).

When the microgame ends, it is your responsibility to hide the hint with "HideHintWithGroup", where you also have the ability to decide whether to mark this hint group as "seen". Usually in MicroWorks, we mark it as seen if the player has won the microgame, so that after winning 3 times, we stop displaying the hint.

Let's create that OnDuckUsed() function. When the duck is used, we want to do a very simple thing:

1. Check if we are the host. If we are, we will register an inflation right away.
2. If we are not the host, we will send an RPC informing the server that we triggered an inflation.


The Client -> Server RPC, will actually just call back to HostRegisterInflation().


Inside HostRegisterInflation(), we're going to want increment the current duck value, and then check if we've passed the required amount. If we have the passed the amount, we will pop the duck and mark everyone as winners. Otherwise, we will update the state of the duck.


Now we need to define the functions for "SetDuckState" and "PopDuck".

In PopDuck, we will shake the player's screen the closer they are to the duck, before deleting the duck. We will also play the duck pop sound.


And the RPC that the host will call for clients:


Now, for duck state, we rely on the ratio to interpolate how big the duck should be between the min and max values we set up. For this, we're going to use "lerp" from lua's math library. (Well, technically, lua's math library doesn't contain a lerp definition, but it's something we added to our lua <3)


And the RPC for syncing it to clients:


That's covers the beginning functions! Thankfully, the bulk of operations happened here, and the other two should be a cakewalk from here.

After setting up OnBeginMicrogame(), we have to set up OnMicrogameTick() and OnPostMicrogame().

We don't need to run any code inside OnMicrogameTick(), so we can leave it empty. Good work, team.

in OnPostMicrogame(), we have to clean up our mess. The entities we create don't get removed by themselves, and it is our responsibility to clean them up.

We will also hide the hint we displayed at the beginning, and reset the duck stats back to 0, for the next time the microgame runs.


And that's it! It took a few functions but our logic is now complete, and that's pretty much how you code for microgames.

With all our logic code ready, all that's left is to register the microgame, just like we learned earlier.

First, we create a variation. Remember to save the return value into a variable!


Then, at the end of it all, we create the microgame:


Congratulations! Your microgame is now ready to be played.

In order to play your newly created microgame, you will launch MicroWorks and create a new server with mutators enabled. In the mutators menu, you will tick "Enable Scripting" on, and if done correctly, you should see your microgame appear at the very top category of "Custom Games".

Unless you're some kind of scripting god, most chances are you'll never get it right the first time, and you better get ready for a bunch of testing and debugging. So here's a few tips:

1. Enable Developer Console. If your microgame is broken, the developer console will point out the issue and the line where the issue occurred.

You can enable the developer console from Settings -> Preferences -> Advanced -> Enable Developer Console, and you invoke it with the tilde key (~). It is strongly recommended to look out for any issues the console might tell you about, specifically after the "Parsing MyScript.lua..." line.

2. Create an empty mutators config. Disabling every single microgame every time so you can specifically test yours is tedious, so make sure to save that configuration so you can restore it next time.

3. You don't have to restart your game. Scripts are reloaded when a level reloads, so if you need to make adjustments to your script, quitting to the main menu and then hosting a new game will work just fine.

Adding new files, however, will require a game restart.

4. Private your server when testing. You don't want people joining when you're trying to test stuff, right?

5. Ask for help. If you're stuck, the community is here to your aid.

Steam Forums
Discord[discord.gg] (faster response)

You've worked hard, you've tested your microgame, and it's finally ready to see the light of day. It's time to upload it.

In order to upload to the workshop, you will have to package your contents into a .alf file. Launch MicroKit once more, and at the top bar, navigate to Tools -> ALF Browser.

Remember how we said "StreamingAssets" is the root folder? That will be our reference point to the root folder in the alf browser. We're going to package all the required files for the microgame.

Thankfully, because we were nice and tidy, we've kept all our content inside of the "Microgames" folder, and so that's the only folder we'll need to import.

When we select a directory in the ALF browser, files or folders we import will import into that selected directory. Therefore, let's select the root directory "\", and click on "Add Folder". (PROTIP: Right click on a directory to select it without folding/unfolding it)

We'll navigate to our StreamingAssets folder, and select "Microgames". This will import the folder and all of its contents.

If done correctly, your ALF browser should look like so:



Now all that's left is to hit "Save Package", and our .alf should be generated. If you want to double check that you've packaged it correctly, you can create a new folder in StreamingAssets called "Mods", and put your .alf file in there. If packaged correctly, the game will read and load it.

Remember to clean up the local source files in your StreamingAssets folder before starting work on a new mod!

Now, for the uploading part: in MicroKit again, we will go to Tools -> Workshop Manager, where you'll be prompted to fill in a few details about your item:

* Item - Allows you to select a previously uploaded item for updating. Keep at "New Item" to upload a new workshop item.

* Tags - Select all that apply to your workshop item:

- Microgame
- Boss Stage
- Gamemode
- Has Custom Level

* Visibility - The privacy status of your mod.

- Public
- Friends Only
- Private
- Hidden (public and shareable, but won't show up in the workshop)

* Title - The title of your item.
* Path - Path to the .alf file to upload. Click the triple dots ("...") to open a file browser to navigate with.
* Description - A description of your item.
* Thumbnail - A thumbnail to your mod.



When all looks right to you, hit the publish button and sit back in accomplishment. Your custom microgame is now live!

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

1. Add a microgame descriptor (.mcg) into StreamingAssets/Microgames
   
   
2. We specify the microgame data and the path to the .lua script
   
   
3. In the script, we call CreateMicrogameVariation() with the name of the variation and 3 functions for when the microgame begins, for when the microgame ticks, and for when the microgame ends
   
   
4. At the end, we call CreateMicrogame() with the name of the microgame, the music table, the variation table, and additional parameters about the microgame

Congratulations on making it to the end... of Part 1! In this part, we learned how to script and how to create custom microgames.

In the next part, we will learn how to create custom levels and custom boss stages.

Modding Pt. 2: Custom Boss Stages

Once again, remember that the sources for the mods we create here are available in this Google Drive folder.[drive.google.com].

For any questions, please reach out to us: https://agiriko.digital/contact/

See you in the next part!