🥧 Butterscotch 🥧
> [!IMPORTANT]
> Butterscotch is still VERY early in development and it is NOT that good yet.
When you create a game in GameMaker: Studio and export it, GameMaker: Studio exports the game code as bytecode instead of native compiled code, and that bytecode is compatible with any other GameMaker: Studio runner (also known as YoYo runner), as long as they have matching GameMaker: Studio versions. This is similar to how Java applications work.
This is how projects such as [Droidtale](https://mrpowergamerbr.com/projects/droidtale) (which was also made by yours truly) can exist. We exploit that GameMaker: Studio games compile to bytecode, which means they can be ran on *any* platform that has an official runner for it!
Ever since I created Droidtale 10+ years ago, I had that lingering thought in my mind... If GameMaker games use bytecode, what prevents us from creating our *own* runner? And if we can write our *own* runner, what prevents us from porting GameMaker: Studio games to other platforms?
And that's where Butterscotch comes in! Butterscotch is an open source re-implementation of GameMaker: Studio's runner.
**Butterscotch Web (WASM):** https://butterscotch.mrpowergamerbr.com/web/
**Butterscotch PlayStation 2 ISO Generator:** https://butterscotch.mrpowergamerbr.com/
## Game Compatibility
Butterscotch's goal is to be able to have Undertale v1.08 (GameMaker: Studio 1.4.1804, WAD Version 16) fully playable. But we do want to support more GameMaker: Studio games in the future too!
While our target is Undertale v1.08, that doesn't mean that other games CAN'T run in Butterscotch! Because Butterscotch is a runner and not a Undertale port/remake, you CAN run other GameMaker: Studio games with it and, as long as the game is compiled with GameMaker: Studio 1.4.1804 and they only use GML variables and functions that Butterscotch supports, it should work fine.
Butterscotch supports the following WAD versions:
* WAD Version 8 (GameMaker: Studio 1.0.198+)
* WAD Version 9 (GameMaker: Studio 1.0.527+)
* WAD Version 10 (GameMaker: Studio 1.1.609+)
* WAD Version 11 (GameMaker: Studio 1.1.754+)
* WAD Version 12 (GameMaker: Studio 1.1.867+)
* WAD Version 13 (GameMaker: Studio 1.1.917+)
* WAD Version 14 (GameMaker: Studio 1.4.1464+)
* WAD Version 15 (GameMaker: Studio 1.4.1675+)
* WAD Version 16 (GameMaker: Studio 1.4.1767+)
* WAD Version 17 (GameMaker: Studio 2.2+)
Other modding tools, such as UndertaleModTool, calls it "bytecode version" instead of "WAD version". We decided to go with WAD version instead because there are GameMaker: Studio versions (WAD version 6 and 7) that DO NOT use bytecode altogether, so calling it "bytecode version" is not quite correct, and because that's what the YoYo Runner calls it under the hood.
Versions before GameMaker: Studio 1.0.198 (that is, pre-WAD version 8) uses raw GML code interpreted on load, so these versions would require a GML compiler to be supported in Butterscotch.
However, that doesn't mean that a game that uses a compatible version WILL run! The bytecode support is still a WIP, and Butterscotch may have quirks that the original GameMaker: Studio runner may not have.
Of course, there are exceptions that break game compatibility altogether:
* Games compiled with YYC, because they use native code instead of bytecode.
* Games compiled with the new [GMRT](https://github.com/YoYoGames/GMRT-Beta/tree/main), because they use native code instead of bytecode.
## Supported Platforms
* Windows
* Web
* PlayStation 2
* PlayStation 3
* ...and maybe more in the future!
Additionally, any platform with reasonably complete C and POSIX conformance should work, the following have been tested.
* Linux with glibc as old as about ~1996
* FreeBSD as old as 2.2.8
* Haiku
The following backends are available for desktop platforms (Windows and POSIX systems).
* GLFW 2
* GLFW 3
* SDL 1.2
* SDL 2
* SDL 3
The following compilers have been tested to successfully build butterscotch, older versions may work but are untested.
* GCC 2.7 and up in C++ mode, and 3.0 and up in C99 mode
* Clang 1.1 and up
* TinyCC 0.9.27 and up
* MSVC 19.29.30159 and up
## Community Ports
* [Xbox 360 (Butterscotch-360)](https://github.com/ceilingtilefan/Butterscotch-360) by @ceilingtilefan
* [3DS and Wii U (Cinnamon)](https://github.com/Project-Sunshine-Native/cinnamon) by @casrielasriel, @grayforz24682, @d16.dorian, @ralcactus
## Building Butterscotch
```bash
mkdir build && cd build
cmake -DPLATFORM=desktop -DDESKTOP_BACKEND=glfw3 -DCMAKE_BUILD_TYPE=Debug ..
make
```
If you are using CLion, set the platform in `Settings` > `Build, Execution, Deployment` > `CMake` and add `-DDESKTOP_BACKEND=glfw3`
Then run Butterscotch with `./butterscotch /path/to/data.win`!
## CLI parameters
The desktop target has a lot of nifty CLI parameters that you can use to trace and debug games running on it.
```
--help - Show this message
--screenshot - Specify the filename for screenshots
--screenshot-at-frame - Take a screenshot at the specified frame
--screenshot-surfaces - Take a screenshot of all surfaces at the specified frame
--screenshot-surfaces-at-frame - Specify the filename for surface screenshots
--headless - Launch without a window
--print-rooms - Print all rooms in the game and exit
--print-objects - Print all objects in the game and exit
--print-shaders - Print all shaders in the game and exit
--print-declared-functions - Print all declared functions in the game and exit
--print-unknown-functions - Print all unknown functions used by the game and exit
--trace-variable-reads - Trace variable reads
--trace-variable-writes - Trace variable writes
--trace-function-calls - Trace function calls
--trace-alarms - Trace alarms
--trace-instance-lifecycles - Trace instance creations and deletions
--trace-events - Trace events
--trace-collisions - Trace collisions between instances
--trace-event-inherited - Trace event inherited calls
--trace-tiles - Trace drawn tiles
--trace-opcodes - Trace opcodes
--trace-stack - Trace stack
--trace-frames - Log frametimes
--always-log-unknown-functions - Always log unknown function calls instead of once per script
--always-log-stubbed-functions - Always log stubbed function calls instead of once per script
--exit-at-frame - Exit at the specified frame
--trace-bytecode-after-frame - Delay stack and opcode tracing until the specified frame
--dump-frame - Dump the runner state at the specified frame
--dump-frame-json - Dump the runner state in json at the specified frame
--dump-frame-json-file - Specify an output file for runner state dumps
--speed - Set a normal speed multiplier
--fast-forward-speed - Set a fast-forward speed multiplier
--seed - Seed for the random number generator
--debug - Enable debug mode
--disassemble