SPG:Overlay Scripts

From Sonic Retro

Sonic Physics Guide



It might not be enough to simply have collision information explained and demonstrated in images, sometimes something interactive helps a concept become fully understood. An overlay script will do just that, allowing collision information to be directly visible as you play the game. Sometimes you may see things which aren't yet explained in the guide at all. It's all on display.

Scripts like these read the data directly from the game as it is being played, to capture information about the states of the player, and of all objects currently active. This data is processed and displayed back in an intuitive way to show hitboxes, solid object collision, and other information such as the state of objects, the variables of the player, and more.

What you see using this overlay may differ to the handmade visuals on the guide. Such as:

  • Sensors are shown in colours according to their direction, rather than labelling them. So Sonic's A + B sensors will both be one colour, and when he is in wall Mode, they will change to the colour for sensors facing that side.
  • Movements of collision information by default are placed where they were executed, which is oftentimes before the object has moved, so they may "appear" to lag behind but is totally normal. To get smoother visuals, a smoothing option is available.

How to use

These scripts are specifically designed to be ran using Gens Re-Recording. When you have the game running, simply navigate to Tools > Lua Scripting > New Lua Script Window. In the window that opens, you can load the .lua file and it will run immediately. While all the classic Sonic games share a LOT of code, the scripts rely on the exact positions in the rom of lines of code, so the scripts must be specially built for each game.

Things to note

  • These scripts show collision as it happens, where it happens. This is great for frame by frame analysis, as collisions between hitboxes or sensors can be accurately read and understood. However, collision events don't always happen AFTER an object moves. In fact, most don't. This can result in the appearance that object's hitboxes or solid boxes lag behind as they move because, well, they effectively do. If you don't like how this looks, luckily there's an option called "smoothing" which will always draw information where the object appears onscreen, rather than where the collision actually happened.
    • If disabled, you see collisions as they have truly occurred that frame. Sensors might shake a bit when walking on slopes, solidboxes and hitboxes may appear to lag behind moving objects (except for Sonic, but it will when he is standing on a moving object), this is because these checks occur before the object moves.
    • If enabled, it shows the sensors/boxes relative to the final screen position of the object, even if the collision check happened before the object moved (which is usually the case). Looks nicer, but isn't accurate.
      • One of the more notable differences is the Player's wall sensors will extend as they speed up with smoothing enabled. This is because his wall sensors do in fact extend outwards, and are cast before the Player moves. However, when they do move they catch up with the previously extended wall sensor and finally after that the floor sensors are cast. So, when you see the sensors as they truly are you will not notice this but seeing all the sensors relative to the Player's final position, it becomes very apparent. But of course, again, inaccurate.
  • Sensors by default are drawn as lines but to be clear, the lines are only there to make the sensor easy to see and to show it's direction, all that really matters is the white sensor anchor point at the end of the lines.

Colour Key

  • Solid Tile Sensors facing Up, Down, Left, and Right.
  • Hitboxes for the Player and other objects (colour varies based on hitbox type).
  • Solid Objects which the Player collides with, and other various Solid object indicators such as platforms and the walkable X range (colour varies based on solidity type).
  • Sizes (aka Width Radius/Height Radius) of objects.
  • Trigger Areas of objects, which are areas where Sonic's X and Y Position needs to be within to trigger a reaction.
  • Solid Tiles/Terrain
    • Fully Solid
    • Top Solid only
    • Sides & Bottom Solid only
    • "*" Flagged Tiles

Sonic 1 Overlay

This overlay shows all the collision processes going on behind the scenes in normal Sonic 1 gameplay.

  • The special stages have been avoided since there is limited revealing information to be shown there.
  • This overlay is designed for use with Sonic 1 REV01 (with the moving clouds in GHZ), and will not work correctly with other games or versions.

There are various options available:

  • Q to toggle the overlay
  • W to toggle the shortcut list
  • E to toggle player variables like speed and position.
  • R to change the darkening
  • T to toggle camera bounds
  • Y to toggle hex values
  • U to change terrain/angle display
  • I to toggle object hitboxes
  • O to toggle object trigger areas
  • P to toggle object sensors
  • F to toggle object solidity
  • G to toggle object width and height radius
  • H to toggle object info (like name and id)
  • J to toggle smoothing effect
Download.svg Download SPG:Overlay Scripts
File: SPGSonic1Rev01Overlay.lua (72 kB) (info)
Current version: 2.2

Sonic 2 Overlay

Just like the first, this overlay shows the collision going on behind the scenes in normal Sonic 2 gameplay.

  • The special stages have been avoided since there is limited revealing information to be shown there.
  • This overlay is designed for use with the final release of Sonic 2 (16-bit), and will not work correctly with other games or versions.

There are various options available, the same as Sonic 1 overlay, with one addition:

  • K to change terrain layer display
Download.svg Download SPG:Overlay Scripts
File: SPGSonic2Overlay.Lua (103 kB) (info)
Current version: 1.1