Engine originally used on Mind Games Mod, intended to be a fix for the vanilla version's many issues while keeping the casual play aspect of it. Also aiming to be an easier alternative to newbie coders.
This is a maintained fork of Psych Engine (by MeguminBOT), branched from the archived upstream repo. It modernizes the toolchain, hardens the engine, and extends what mods can do — while staying a drop-in upgrade for existing Psych mods.
Goals
- Stay current & buildable — track up-to-date library versions (HaxeFlixel 6, OpenFL 9.5, Lime 8.3, LuaJIT via
hxluajit, scripting viahscript-insanity) with a self-contained, reproducible setup that won't collide with other Haxe projects. - Stability first — fix the long tail of vanilla crashes, null-pointer faults, off-by-one and mid-iteration bugs (80+ targeted fixes so far).
- Performance — cut per-frame allocations and redundant work across input, scripting, note spawning and the HUD (30+ perf commits).
- Safer mods — let players run community mods with less risk via an opt-in script-scanning sandbox.
- Better scripting & modding ergonomics — class/state-level scripting, a real-Lua mode, modpack types, and more configurable engine features.
Headline changes
- Modernized dependencies — major upgrades to Flixel/Flixel-Addons, OpenFL, Lime;
linc_luajit→hxluajit,hscript-iris→hscript-insanity,flxanimate→flixel-animate. - ModSecurity — scans a mod's Lua/HScript on enable, flags risky calls (
os.execute, reflection tampering, etc.), and prompts to Trust or Block per mod. Configurable in Misc options. - Modpack types —
pack.jsonnow distinguishes globally-running Script Packs from local Mod Packs (with opt-inrunsGlobally). - Scripting upgrades — class/state-based scripted states, plus selectable Lua modes (
compatlegacy callbacks vs.rawreal-Lua object access) and a configurable State Source. - Configurable FPS / performance counter — position, color, font size, update rate, and toggleable FPS / Memory / Peak / CPU / GPU / VRAM readouts (CPU/GPU/VRAM via the optional
hxhardwarelib). - Setup overhaul — pinned, dependency-isolated
haxelibsetup with a project-local.haxelib/repo andhxcppbuilt from source.
See docs/FORK_CHANGES.md for the full changelog and docs/MIGRATION_1.0.4_to_1.1.md for migration notes.
Refer to the Build Instructions
If you wish to disable things like Lua Scripts or Video Cutscenes, you can refer to the Project.xml file.
Inside Project.xml, you will find several variables to customize Psych Engine to your liking.
To start you off, disabling Video Cutscenes should be simple, simply delete the line "VIDEOS_ALLOWED" or comment it out by wrapping the line in XML-like comments, like this: <!-- YOUR_LINE_HERE -->
Same goes for Lua Scripts, comment out or delete the line with LUA_ALLOWED, this and other customization options are all available within the Project.xml file.
For this you can head over to the wiki
There you can learn how to use the 212 PlayState funcions in your mod!
- Shadow Mario - Main Programmer and Head of Psych Engine.
- Riveren - Main Artist/Animator of Psych Engine.
- bbpanzu - Ex-Team Member (Programmer).
- crowplexus - HScript Iris, Input System v3, and Other PRs.
- Kamizeta - Creator of Pessy, Psych Engine's mascot.
- MaxNeton - Loading Screen Easter Egg Artist/Animator.
- Keoiki - Note Splash Animations and Latin Alphabet.
- SqirraRNG - Crash Handler and Base code for Chart Editor's Waveform.
- EliteMasterEric - Runtime Shaders support and Other PRs.
- MAJigsaw77 - .MP4 Video Loader Library (hxvlc) and LuaJIT bindings (hxluajit / hxluajit-wrapper).
- Vortex2Oblivion - hxhardware, the native CPU/GPU/Memory library powering the FPS counter.
- inky03 - hscript-insanity, the HScript extension fork used for scripting.
- iFlicky - Composer of Psync, Tea Time and some sound effects.
- KadeDev - Fixed some issues on Chart Editor and Other PRs.
- superpowers04 - LUA JIT Fork.
- CheemsAndFriends - Creator of the original FlxAnimate library.
- MaybeMaru - Creator of flixel-animate, the Texture Atlas backend used in 1.1+.
- Ezhalt - Pessy's Easter Egg Jingle.
- MaliciousBunny - Video for the Final Update.
- A brand new menu that makes your experience even better!
- Probably one of the main points of this engine, you can code in .lua files outside of the source code, making your own weeks without even messing with the source!
- Comes with a Mod Organizing/Disabling Menu.
- New Dad Left sing sprite
- Unused stage lights are now used
- Dad Battle has a spotlight effect for the breakdown
- Both BF and Skid & Pump does "Hey!" animations
- Thunders does a quick light flash and zooms the camera in slightly
- Added a quick transition/cutscene to Monster
- BF does "Hey!" during Philly Nice
- Blammed has a cool new colors flash during that sick part of the song
- Better hair physics for Mom/Boyfriend (Maybe even slightly better than Week 7's 👀)
- Henchmen die during all songs. Yeah :(
- Bottom Boppers and GF does "Hey!" animations during Cocoa and Eggnog
- On Winter Horrorland, GF bops her head slower in some parts of the song.
- On Thorns, the HUD is hidden during the cutscene
- Also there's the Background girls being spooky during the "Hey!" parts of the Instrumental
- You can now chart "Event" notes, which are bookmarks that trigger specific actions that usually were hardcoded on the vanilla version of the game.
- Your song's BPM can now have decimal values
- You can manually adjust a Note's strum time if you're really going for milisecond precision
- You can change a note's type on the Editor, it comes with five example types:
- Alt Animation: Forces an alt animation to play, useful for songs like Ugh/Stress
- Hey: Forces a "Hey" animation instead of the base Sing animation, if Boyfriend hits this note, Girlfriend will do a "Hey!" too.
- Hurt Notes: If Boyfriend hits this note, he plays a miss animation and loses some health.
- GF Sing: Rather than the character hitting the note and singing, Girlfriend sings instead.
- No Animation: Character just hits the note, no animation plays.
- Working both for Source code modding and Downloaded builds!
- Added a different BG to every song (less Tutorial)
- All menu characters are now in individual spritesheets, makes modding it easier.
- You can add a head icon, name, description and a Redirect link for when the player presses Enter while the item is currently selected.
- The engine comes with 16 example achievements that you can mess with and learn how it works (Check Achievements.hx and search for "checkForAchievement" on PlayState.hx)
- You can change Note colors, Delay and Combo Offset, Controls and Preferences there.
- On Preferences you can toggle Downscroll, Middlescroll, Anti-Aliasing, Framerate, Low Quality, Note Splashes, Flashing Lights, etc.
- When the enemy hits a note, their strum note also glows.
- Lag doesn't impact the camera movement and player icon scaling anymore.
- Some stuff based on Week 7's changes has been put in (Background colors on Freeplay, Note splashes)
- You can reset your Score on Freeplay/Story Mode by pressing Reset button.
- You can listen to a song or adjust Scroll Speed/Damage taken/etc. on Freeplay by pressing Space.
- You can enable "Combo Stacking" in Gameplay Options. This causes the combo sprites to just be one sprite with an animation rather than sprites spawning each note hit.