Adding A Map - Modding Guide

When I made Poltersprite, I hadn't participated in game jams before. I had never opened GB Studio a day in my life. I joined GitHub Game Off 2024 with roughly 2 weeks left until the deadline on an impulse, just to see if I could make a game in the short timeframe.

Not only did I succeed, but Poltersprite ended up being my most played game to date! At the time of writing this it sits at over 310 browser plays and just shy of 150 downloads. For someone with a very tiny audience, this is incredible! I genuinely never imagined a game I made would be viewed by so many people.

During the jam, I promised to add additional content to the game after voting, once I had wrapped up my other commitments.  It's taken some time to catch up, but I am pleased to report that I am going ahead with the original plan!

I will not be putting a deadline on this, and this month does tend to be rough on me so it may take some time, but Poltersprite will be getting a new, larger map, along with some extra QOL polish, and, if I can swing it, new ghost types and an extra item or two. I am going to do what I can to take this from good to great, as my thank you to all of you for playing my game!

So far, I have made good progress in implementing the new map. The most time consuming part of this is drawing all of the scenes! I was able to reuse much of my existing code to make the added scenes playable within a few hours, which you can do too! Poltersprite's GitHub repo has remained open, meaning you can download the project files, open it up in GB Studio, and add your own maps/items or use it to make something new! Here are the steps I took to add a new map, which you can do using any of the 1.0 releases as a base. I cannot promise this will work on later releases, as the file size may end up too large. And there is a chance I may have missed describing steps as I am scatterbrained. Play around with it!

This guide is quite long, but it is very detailed and pretty much a step by step guide to making a custom Poltersprite map.

• Create blank scenes for your new map. 5-8 seems to be optimal. Lay them out how you would like them connected to make work easy.
• Create a variable to store which map has been selected. I called mine "Map".
• In the "Menu" scene, under the On Init tab, find the Event called "Loop" and expand it. After the Display Choice event for the difficulty, add a second Display Choice event. Set the variable to the one you just created. In the "Set to 'True' if" field, type "House". In the "Set to 'False' if" field, type the name of your new map.
• Next, click on any of the original house scenes and click the down arrow next to the lock icon on the "On Init" tab bar. Click "Copy Script". For each of your blank scenes, click the same arrow and click "Replace Script". This will act as a base that can be modified for any new map.
• Click on the "Truck" scene and expand the event labelled "If $NewGame". Add an "If Variable is 'True'" event, and set the variable to the one you created to track which map has been selected. You are going to need to do this wherever the game has scripts specific to the house. But you need not be overwhelmed, because it is easier than it sounds. Drag the event above all of the Display events, and place the first one inside the If statement. It should look like "If $Map > Display 'Reports say this house is haunted.'" Leave the other statemants where they are. Copy the mentioned Display statement into the Else portion and change the word house to whatever the name of your map is. This is mostly cosmetic, but good practice for what comes next.
• Click the rectangular trigger in the doorway of the Truck scene. Add another If statement as above, but this time for the Change Scene event. If the variable is true, change the scene to the Living Room. If false, change to your new map's starting room (and set coordinates)
• Time to modify some scripts. Open the "Ghost randomizer" script. Create If statements as you did the past two steps for both the "$Room = Random(0,4)" and the "$BoneRoom = Random(0,4)" events, placing them in where the variable is true. Where the variable is false, copy these events but change the range to the number of scenes you have added, minus 1. (ie if your new map is 7 scenes, the range will be (0,6))
• Open the "Sanity Hunt" script. Create yet another If statement using the map variable. Drag ALL of the "If($Room == x)" statements into the true section. In the else section, you will need to copy these statements down for as many scenes you have added, incrementing the comparitive value each time. Under each one, change the Current Scene check to your new scenes. Make note of what order you put them in, as you will need to keep this consistent. (ie your Entrance can't be Room 1 in this script and Room 3 somewhere else). Leave the rest of the script the same.
• Open the "Extra Hunt" script. This handles hunts that start when the player is not in the ghost room. Expand the "If ($Sanity <= 50)", "If !(HuntCooldown)", and "If ($ExtraHuntCheck >= 60)" events. Add another If statement at the bottom of this collection of events and drag the "If Current Scene Is Living Room" event into the true section. Copy it into the else statement and expand it. This section goes through each room and sets where the ghost will spawn based on where its room is in relation to the active room. Set the first current scene check to your first new scene. Here, you will need to modify the following "If ($Room == x)" statements to match your map. For example, if your first room has two paths to take out of it, you may want to rewrite this to say "If ($Room == [number of Room on left]" and then set the NewX and NewY positions to the left doorway. For efficiency, don't write checks for every room. If most of your rooms will lead the ghost through one doorway, put those coords in your else statement and only write other If statements for the exceptions. Do this for every scene you have added.
• Almost there! This time you're going to create a new blank script. Call it "Use Item 2" or something similar. What needs to happen is the "Use Item" script needs to be copied to this new script, but modified for your new map. This is solely because GB Studio will yell at you for the file being too large otherwise. Copy the entire thing using the arrow next to the lock icon, then expand the button script and On Press events. This part is also very easy. Going through the "If ($Room == x)" statements, assign each value to the appropriate scene in your new map in the Current Scene check. If you need more statements, just add an additional Else If at the bottom of the stack, increment the room number, and copy the entire Current Scene event from an above section into it before changing the scene.
• One more script patch! Open the "Timer" script and expand the "If $MenusEnabled" and "If !($Hidden)" events. Make another If statement checking your map variable in here, and drag the "Call Script: UseItem" event into the true section. Call your new script in the else statement.
• Now we need to modify the On Init script we copied into all of the scenes earlier. Expand the "If $MenusEnabled" event and open the "Call Script: UseItem" event. Change it to the new script you just made. Do this for every room. The foundation is now set!
• Click one of the ghosts in the house map, click the arrow next to its name and click "Copy Actor". Hit Ctrl + V on your keyboard and click anywhere inside one of your new scenes to add the ghost. Add one in every one of your new scenes. Every room needs a ghost!
• Click the small rectangle in the bottom right corner of any of the house scenes, it should be called Actor 2. Copy this into each of your new scenes as well- this controls the ghost! I recommend sticking it in an unused corner so it doesn't interfere with other sprites. You will need to assign the room's ghost to each of these. There are 2 places to set the ghost actor in the "If Hunting and Player Changed Rooms" event stack, under the "If ($DistStore >= $Distance)" event. There are 4 places to set the ghost actor in the "If $RunCheck" event, under the "If $Flicker" event. Make sure you set these for each room. While you are here, set the room comparative value under the RunCheck to the value of the selected room.
• You will also need to set the ghost actor once in each scene's On Init script, directly under the "Call Script: SanityHunt" event. 
• To set up the bone, copy the Bone actor from one of the house scenes into one of your new scenes. In the scene's On Init script, under the "If !($BoneFound)" event, expand until you find the "Activate Bone" event. Set the actor in this event to the Bone you just added to the scene. Set the "If ($BoneRoom == x)" event value to the value of the room you have selected. You now have bone.
• The handprint and knocked over item ghost events are implemented nearly the same way. Copy the actors into your new scenes. Open up the first Else statement in the On Init for each of these and set the room comparitive value to the value of the room you have selected. Try to stagger the locations of your actors around the map to prevent stuttering or cut off sprites, avoiding placing them on the same horizontal or vertical line where it can be helped. Open up the On Update script for Actor 2 in the scene, expand the "If $RunCheck", "If ($Room == x)", and "If !(Hunt)" events. Under the "If $Handprint" and "If $Knocked" events, set the actor to the handprint and item actors respectively. For ghost event items, you can adjust the animation state to a cup or photo frame (upright and knocked). You can customize these sprites by creating a sprite with default and changed visuals and setting up animation states, then reassigning the animation states in the actor itself as well as Actor 2.
• The game is wired to make use of 3 hiding spots, and though you could add more, it is easiest to leave it be. A hiding spot is composed of 2 triggers: an entrance trigger and an exit trigger. The entrance trigger can be found in front of any of the house's wardrobes. The exit trigger can be found at the top left corner of the wardrobe and is square-shaped. Copy the entrance trigger in front of your desired hiding spot location and open up the On Enter script. Expand the "If !($HardMode)" and "If !($Hidden) events. Set the player position to where the exit trigger will be placed. The exit trigger should be placed inside a hiding spot's graphic and surrounded entirely by colliders later. This is to keep the player contained, so they can actually leave the hiding place. In the else statement for the Hidden check, set the coordinates to the coords of the entrance trigger, offset so that the player will not be touching it when they leave the hiding place. You will also need to set these same coordinates under the "If ($HardHiding == x)" event. Make sure the value in this check is labelled 1-3 for each hiding place you add. In the On Enter for the exit trigger, set the player position to the exit trigger's coords if !$Hidden, and to the offset coords from a miment ago in the else statement. You will ALSO need to modify the On Leave of the exit trigger, replacing the Call Script for the new UseItem script you made to ensure items can still be used after.
• The final piece of the puzzle is changing rooms! Click one of the rectangular triggers in the house and copy it into one of the new scenes. Position it where you would like players to collide with it, adjusting the height or width as needed. Set the player direction in the If statement to the direction the player should be facing when walking into it. Under the change scene event, set the scene to the area you would like to change to and adjust the coordinates both here and above inside the "If $Hunt" statement (NewX and NewY). Also set the direction you would like the player to face after the scene changes. Add these triggers, adjusting the script for each path, to every single space that you would like to change to a new area when walked into. And make sure to add them from the other room going back as well!
• You can now drag your maps into the project files' backgrounds folder, under assets, and set the background of each scene to the map you made. Use the bricks icon to access the collisions pens and mark areas that the player should collide with.
• Here's where we clean things up! Open up the Hunt Script to tweak the ghost's movement AI. It is... incredibly simplified. Your job now is to make sure the player can't get the ghost stuck on objects, collisions, or paths. Opening up the "If $Hunt", "Movement", "If !($Hidden)" events, you'll see an "If Current Scene is Kitchen" event. Inside this is a bunch of back to back if statements checking if the ghost is in a certain range of coordinates. If the ghost is in the coordinate range, it should move a certain number of spaces in a specific direction to get itself unstuck. You may also use these to prevent looping by randomizing the ghost's movement if the player attempts to run it in circles around a table, for example. Just add to the else if chain with any scenes you need to do this for, testing as you go.
• If you've followed everything this far (and assuming my brain fog didn't miss explaining any steps), you should be able to play your new map now! 🎉

Much of this process is simply copying and pasting existing scripts and changing variables. Past me was smart enough to make it so, thank you past me. It could probably be optimized better but I frankly do not have the attention span. It runs, that's what matters.

With any luck, I will be back here sooner rather than later with either a guide on adding ghosts/equipment or an announcement for the update. Stay tuned! 🎪🎡