Home
Welcome to this wiki! Psych Engine XTended (or Psych-XT for short) is a fork of Psych Engine with additional tools and improvements, aiming for compatibility with existing Psych modfolders as well for extended modification without need of touching the game's source code.
Note: The current compatibility level of Psych-XT is with Psych Engine 0.6.3. Parity with versions 0.7.X is not planned at the moment, but it should eventually be shipped in a future, major update.
On top of everything Psych Engine brings out of the box for easier modding, Psych-XT includes more goodies of its own. Some of these features work nicely for novice modders, while some others are intended to be leveraged by relatively experienced scripters:
Note: Psych-XT is tailored to work with modfolders. While the examples skip the modfolder name from paths, we recommend always packing the content of your mod inside a modfolder.
If your mod is simple enough (a plain image as stage + the characters on top) but you want to display some dialogues, you will usually need a script to handle that for you, in addition to the dialogue files. In Psych-XT, if you save the dialogue file as dialogue.json inside the data folder of your song, the engine will handle the display of your dialogue automatically in Story Mode, before the song is played for the first time in that run; saving you the step of using a script. In the same fashion, if there's a dialogue file called dialogue-end.json, it will be displayed at the end of the song.
You may, however, still resort to a script if you want to display more stuff or several dialogues in a row. The engine will detect interruptions in the onStartCountdown() and onSongEnd() functions and disable the automatic loading of dialogues.
By default, Psych-XT will look for sounds in mods/sounds/dialogue/ with the name of a character (for instance, boyfriend.ogg) in order to play them as typing sounds. This way you can customize the sound effects of your dialogues easily, simply by placing sound files with the right names.
Psych-XT includes basic support for multiple languages. While the character set of the bitmap fonts included with FNF is limited, changing the language affects the loading of some assets, mainly dialogue files.
In order to work with several languages, first create a file called langs.txt and store it inside mods/data/.
Then fill that file with the languages you want to display, one per line, with the following format: <langCode>|<Language Name>. For example:
es|Spanish (Español)
ita|Italian (Italiano)
The <langCode> piece will be used to search for dialogue assets, while the <Language Name> is what will be displayed when the player chooses a language. This is available in the Options menu by default:
Note: The stock language included with Psych-XT is, of course,
en|English.
When you're loading a dialogue file, the engine will first look for a locale variant of that file. For instance, for the language "Spanish (Español)", the file dialogue.es.json will be looked for first, and if it's not found, dialogue.json will be loaded instead. No other stock asset loading mechanism leverages this by default, but this may change in a future update.
Of course, this doesn't mean your scripts can't make use of this system! Just call getLangCode() and getLangName() from within a Lua script and you will get access to the chosen language code and name, then you may load sounds and images depending on the player's choice. You can also create text labels using actual fonts, breaking past the character limits of the game's own bitmap-based fonts.
By default, neither Friday Night Funkin' or Psych Engine 0.6.3 include special characters like accentuated vowels or latin consonants. Psych-XT incorporates a few of these missing characters, just enough for Spanish and Portuguese text; but they might be lacking for other languages. This is a limitation that will be addressed in future updates.
For the time being, Lua text labels are a much better alternative.
This was originally incorporated for Vs Selver fanmade, but it could come in handy as an easter egg for any other mods, so it's been ported over to Psych-XT. All you need to do is place alternate versions of your backgrounds called menuBGAlt.png (for the main menu) and menuDesatAlt.png (for all other stock menus). These alternate backgrounds have a small random chance to be displayed instead of the normal ones! Suitable for a joke or a scare.
Would you like to include your own intro texts? Those short messages before the splash screen? All you need is to drop a copy of the file assets/data/introText.txt inside mods/data/ and customize it to your heart's content. If your mod is the first or only loaded modfolder, this file will be used to pick messages. Simple as that!
Not only is this project a spin-off of Psych Engine, but the LuaJIT runtime bridge has been forked for it as well. Some improvements have come with this:
- Some Lua functions provided by Psych have been extended with one or two extra parameters, for more flexibility.
- Some new functions have been added, most of them are mainly tailored for menu states.
- Lua functions no longer return their first parameter when they have nothing to return, or they were supposed to return
nil. - Stacking calls from within tables and functions no longer crashes the game.
- It is now possible to submit and receive Lua tables and functions through the API, these are often converted from/to Haxe StringMaps and LuaJIT Function references.
There will be a page soon with the full details on these novelties.
The big novelty in Psych-XT is the ability of running Lua scripts in place of the existing states (main menu, free play, etc.) or to use them as completely unique ones. This way you may code more than just Rhythm games using the engine, and with no need to touch the game's own source code at all! These Lua scripts count with additional functions aside from what's available inside a PlayState, useful for stuff like navigation between states, reading/writing settings, and starting regular FNF games.
The following states are currently supported: main_menu.lua, story_mode.lua, freeplay.lua, awards.lua, credits.lua, options.lua and mod_editor.lua. In order to override any of the available states, just create a script with the right name inside mods/states/ and start filling your state with sprites and text labels from the onCreate() event.
There will be a page soon with the full details on the functions available for Lua states, their capabilities and their current limitations.