Hypnospace Outlaw

Hypnospace Outlaw

Modified content, additional content, and total conversions for Hypnospace Outlaw! Must have HypnOS v2.15 or above to create and use mods.

Learn more and find the game on Steam, GOG.com, itch.io, Discord.

Modder's Reference Manual

Reference material to help modders do their thing! This is meant to be used alongside the Getting Started and Scripting guides.

1 comment

Posted by on (updated ago)


Please be VERY CLEAR in your description if your mod has spoilers or requires knowledge that folks won't have until they beat the game!

Also, MASSIVE SPOILER WARNING!! PLEASE finish the game before you read this guide!

The below assumes you are running Hypnospace Outlaw v2.20 or later!

underconstruction underconstruction underconstruction


  • Ensure any new assets for your mod do NOT use the same filename of any existing assets shipped with Hypnospace!
    • If you are replacing default Hypnospace assets in your mod, make sure you use the exact same filename - these are case sensitive!
  • As a general rule, all filenames should be lowercase!! In most cases you can refer to the files in-game with whatEveR Case YoU CHOOSE, but the actual asset must be all lowercase.


Color Palletes

The top PNG is the final 86 color version, the bottom PNG is a super limited one for icons and stuff:




List of App Window Names

This information is provided for use in 'IsOnScreen:WindowName' what/not scripting, and for reference when creating custom apps (do not use these names)

Settings, DropMenu, Hypnotext, Downloads, Explorer, CitizenData, QuickCheck, QuickCheckSubmit, Resolve, Installer, Soundscapes, HUD, Janitor, Tutorial, HypnoCure1, HypnoCure2, HypnoCure3, Pets, HSPD, ProfHelperDia, Input, Tunebox, Library, Eye, Accel, 2000Update, BrickPlacer, AppMenu, HackApp, Archive, HAP, OSKeyboard

Deprecated and/or unused windows:
VGame, Wallet, Wallet2, PowerMenu

List of valid Layouts

For use in RSOD scripting, and any other scripts used to go to another Layout

BootScreen, Menu, HypnOS, Highway, RSOD, BIOS, Y2K

List of valid Screensavers

For use in StartScreensaver:name and SwitchScreensaver:name scripting

Marquee, HSLogoBounce, Snixels, Squareburst, Planetarius, BrickLayer, Ooozle, Ooozle Sphere, Ooozle Drip

Example: SwitchScreensaver:Squareburst

List of valid Viruses

For use in Virus:name scripting

MouseRPG*, ButtsDisease, BPMWarp, WaveHello, Autoscroller*, TheHunger, FlyingWinz, FesteringOrifice, SmearPaper

*MouseRPG is not used because it does not work on every PC, and Autoscroller is unused as it is too difficult to cure

Example: Virus:ButtsDisease

List of Icons and File Types

Use DownloadFile:path\to\file.ext or CreateDesktopIcon:path\to\file.ext to automatically set file type, or create your own custom icon by using the following scripts. File icons can be deleted by the user, but System Icons must be deleted via scripts (RemoveSystemIcon:Name).


Example: CreateFileIcon:HypnoHax.hex,5,HaxxorJax,15,downloads\hypnohaxscript.txt

*Recycle bin can hold 400 units total. Keep this in mind when setting the Size parameter.


1 - Document
.htx, .txt

01small 00

2 - Audio
.hsm, .hmu, .aud, .ogg

02small 01

3 - Image
.him, .png

03small 02

4 - Video
.htv, .webm

04small 03

5 - Executable
.hex, .app

05small 04

6 - Wallpaper

06small 05

7 - Screensaver

07small 06

8 - Game

08small 07

9 - System

09small 08

10 - Theme

10small 09

11 - SFX Theme

11small 10

12 - Soundscape

12small 11

13 - Pet

13small 12

14 - Danger
.xyz, .xxx

14small 13


Example: Hypnocure ULTRA,Virus:FlyingWinz,HypnoCure

Animation names:


system waller


system tutorial


system tunebox


system tombstone


system sticky


system soundscape


system settings


system profhelper


system power


system pets


system janitor


system janitorclose


system hypnocure


system hypii


system hspd


system highwayalpha


system highway


system hackapp


system eye


system explorer


system everythingsearch


system downloads


system chat


system brickplacer


system axxelerator


system archive

Window Icons (for ads and custom apps, 0-indexed):


Pop-up Icons (for use in pop-ups messages, 12th parameter, 1-indexed):


List of valid Signals

Modders can use the script WaitSignal to make a script wait until called, either with custom "Signals" (using Signal:MySignal), or by listening for some of the built-in signals in HypnOS. These are listed below. Many of them are used only for internal processes, but are listed below for the sake of completion.

IMPORTANT: Scripts using WaitSignal can NOT be made persistent!! If they need to run at all times, start the script within your config.ini file's OnBootScript.

  • [AppName]Dropped - Player dragged and dropped this app
  • [AppName]Opened - This application just opened
  • [AppName]Closed - This application just closed
  • [AppName]DoneShaking - This application just stopped shaking (example: 'shake:Settings')
  • CureMe - The player just used the 'Cure Me' function in HypnoCure
  • Virus_[VirusName] - This virus was just removed from quarantine <HypnOS v2.22e+>
  • InputComplete - Player typed something into the input box and hit OK, or cancelled it. This does NOT happen upon inputting data in an InputWait style input box.
  • CaseClosed - Player just closed a case
  • CaseClosedEnd - The case-close stamp finished flying away
  • TutorialDone - Player completed the tutorial, or dragged it into the trash can to force-complete it.
  • DoneScooting - Webpage scooted over to the left or right to make room for an opened or closed toolbar
  • SearchIndexed - The search index completed building in the background (happens upon the player using the Explorer's search function, but only when search data may have changed due to in-game events)
  • ProfHelperGone - Professor helper just moved out of screen
  • JanitorClosed - Player exits out of the Janitor app
  • TutorialImageLoaded - An image just finished loading in the Tutorial.
  • CaseImageLoaded - A case's image just finished loading in the HSPD Cases tab
  • HypnoVideoLoaded - Video loaded up and is playing.
  • HypnoImageLoaded - Image loaded up in the Hypnofile Observer app.
  • PlayerProgressionComplete - Player progression data has been fully checked (This is an internal process that happens during the splash screen as HypnOS is loading up.)
  • ArchiveBuilt - Archive (capture) data finished building during boot-up (This is an internal process that happens during the splash screen as HypnOS is loading up.)
  • SplashEnd - Signals upon the splash screen fading away (This is an internal process that happens during the splash screen)
  • StartupComplete - Signals after SplashEnd, after the game is saved
  • CharProgressionComplete - [DEPRECATED] Previously used to update character data upon going to the 'next day' (which is also deprecated)


How to add custom wallpaper

To add a custom wallpaper to your mod, put a .png image file sized 480x270 in the folder \os\wallpaper, titled with all lowercase characters. Then, depending on what you want to do, use one or more of the following scripts (case-sensitive):

InstallWallpaper:myfile.png / AddWallpaper:myfile.png / LoadWallpaper:myfile.png

If you simply want the wallpaper to be immediately available to the player, use Install (which can be cancelled) or Add in your config.ini's InstallScript. Remember to use RemoveWallpaper in the UninstallScript.

How to add a custom screensaver


To use a video as a custom screensaver, put the video in the folder \os\screensavers\ in webm format with a .htv extension. Then, depending on what you want to do, use one or more of the following scripts:
InstallScreensaver:[MyVideo] / AddScreensaver:[MyVideo] / StartScreensaver:[MyVideo] / SwitchScreensaver:[MyVideo]

The screensaver video should scale to match HypnOS resolution (480x270) and will have the audio muted. Note that there should be no extension added to the file name, and it is non-case sensitive so you can input the text exactly how you'd like it to show up in the Settings app.


To use custom images in a Flying, Falling, or Space style screensaver, create a new folder in \os\screensavers\[yourfolder] (titled with lowercase characters only), add your images to the folder in .png format, and add an empty text file titled "clear.bg" if you want a transparent background. Then, depending on what you want to do, use one or more of the following scripts:

InstallScreensaver:xxx / AddScreensaver:xxx / StartScreensaver:xxx / SwitchScreensaver:xxx
Where 'xxx' is Space[YourFolder] / Falling[YourFolder] / Flying[YourFolder]

If you simply want the screensaver to be immediately available to the player, use Install (which can be cancelled) or Add in your config.ini's InstallScript. Remember to use RemoveScreensaver in the UninstallScript. Note that folder name in the script is non-case sensitive so you can input the text exactly how you'd like it to show up in the Settings app.

How to add/modify characters in your mod

PageBuilder -> Character Editor -> Export Character Data

Choose the characters you've added/modified, click Export

IMPORTANT: Due to a bug in the game engine we use, you'll need to manually edit the exported data file!! This is true in the Page Builder shipped with v2.23 on Steam, I'm not sure about previous versions of the page builder, or versions shipped elsewhere.
Open your exported data file, chardata.hsd, in notepad. At the very beginning you'll see the following: {"c2array":true,"size":[2,21,21],"data":. You will need to reduce the first number in [brackets] by one, i.e. if your file states [2,21,21] change it to [1,21,21]. DO NOT alter any other information in this file!
The number must be equal to the number of characters in the data file minus 1. I'm not sure why the engine exports these data files with the wrong number, but it does.

Put the resulting chardata.hsd file in your mod folder under \misc\

How to add a custom virus

Custom viruses are fairly advanced, so here I'm going to explain a relatively simple virus that just shows an ad every 20-40 seconds. We will need three scripts:

  • one persistent, repeating script that shows the ad (myradvirus.txt)
  • another that listens for the player to use HypnoCure to cure the virus (myradcure.txt)
  • and a third that listens for the player to use HypnoCure Pro to remove the virus from quarantine (myradunquarantine.txt)

The repeating virus script itself must be "persistent" so that it continues if the player logs out or restarts. The 'cure' script needs to run via your mod's 'OnBootScript' and repeat, so that it is always listening for HypnoCure, as does the 'quarantine' script. We will be storing these scripts in three separate files, 'myradvirus.txt', 'myradcure.txt', and 'myradunquarantine.txt' and put them in a folder \downloads\myradscripts\ within your mod's directory.

In your mod's config.ini file, add the following script to your OnBootScript - openfile:downloads\myradscripts\myradcure.txt|openfile:downloads\myradscripts\myradunquarantine.txt

And toggle your virus similarly, either by having the player download and run a file, click a link on a page, etc, using this script: openfile:downloads\myradscripts\myradvirus.txt



This script file will (in order of script functions separated by | ) ensure the script persists if the player logs out or restarts, give the script the tag name "myradvirus", initialize a new variable in memory 'radvirusdelay', apply the virus "MyRadVirus" in HypnoCure, set script variable 'radvirusdelay' to a random number between 20-40, wait for that number of seconds, show myradad, and repeat 99,999 times starting at script command 4 (zero-based, so the 'randvar:' command).



This script file will (again, in order), wait until the player uses Cure Me in HypnoCure, end the myradvirus script, cure the virus in HypnoCure, and repeat starting at 'waitsignal' in case the player is infected with the virus again, and they click CureMe again.

Note: "CureMe" is a special "signal" that HypnoCure calls out when the player uses Cure Me. There are some other signals out there you can listen for, listed above.



This script file will (again, in order), wait until the player removes the virus from quarantine in HypnoCure Pro, start up the myradvirus script, and repeat starting at 'waitsignal' in case the player cures the virus then removes from quarantine again.

Note: "Virus_VirusName" is a special "signal" that HypnoCure calls out when the player removes a virus from quarantine

How to add a custom Email

Create a new text file in your mod folder: [yourmod]\misc\emails.ini

Take a look at the emails.ini file in the default asset folder for more details on how emails are set up!

Add the following text to your new ini file:

Subject=Subject of the email
Body={{The body of your email enclosed in double-curly brackets
Line breaks are respected!
Add a link like so:
link:hs\01_hypnospace central\merchantsoft.hsp
>Tab in, as if we are quoting a previous email
>Add a citizen's avatar in the middle of an email like so:
>More text!
>>A 2nd tab!!
>>>A 3rd tab!!!
>>>links can go here too:
>>>link:hs\01_hypnospace central\merchantsoft.hsp
>>>/p will be replaced with the player's name, /t with a tab, /n with a new line, and  #ScriptVariables# work too =) }}

Make sure you use a unique EmailTitle. If you use one that already exists within the default emails.ini asset file, your email will overwrite the default one (if this is intentional, great! Go for it!!).

Set the Important variable to 1 if you'd like it to be marked as 'important', and reported out as such by Hypii. Set it to 0 otherwise.

Attachments can be left blank if there are none, and multiple attachments can be added by separating with a pipe | character.

If your email is sent from a custom character, or one with no existing avatar, you can add their avatar here: [yourmod]\images\avatars\citizenname.png (filename all lowercase, 30x30 pixels)

Adding custom Music

Custom sample files for music made in the Sequencer should be saved as .ogg format and put here:

Music made using the Sequencer tool (musicfile.hsm) should be put here:

HypnOS can also accept .ogg music files. Put those here:

Ogg music files must also have a .txt file named exactly the same as the .ogg file ([yourmod]\audio\music\yoursong.txt), with the following contents separated by a pipe|character:
Song Name|Artist Name

OS Theme Guide

Cursor Theme Guide


SFX Theme Guide

How to use Character Events to create dynamic pages

How to use Script Variables to create dynamic pages

Editing Player Progression Logic

Links and Link Scripts in pages

Debug functions

Toggle an FPS counter at the top-right by holding F+P and pressing the S key.

Put the game in Debug mode by holding the D+E keys and pressing B during boot-up. Whenever the boot-screen appears it will reset the game into non-debug mode, so remember to do this every time you see the boot screen.

Once in normal Debug mode, you can go into Active Debug mode by holding D+E and pressing B on your HypnOS desktop. This allows for additional debug functionality.

Enable the Console by going into BIOS from the main menu and checking the box to enable it. Use the ~ or ` or § key to enable and disable the console in-game. Use the console to type in custom scripts for testing and debug purposes (and hax!).

In Debug mode, you can:

  • View the developer tools window by holding D+E and pressing V at any time (not supported on Mac, may or may not be supported on Linux)
  • Hold Q to skip through boot-up
  • Hold R to increase the time-scale
  • Hold T to go into slow-motion
  • Hold S to debug sound and soundscape stuff
  • Hold Q to speed up the splash screen (can cause problems since lots of things are loading and being initialized here!!)
  • Press F3 to view all player settings
  • Hold CTRL and press numberpad buttons to move the camera around and zoom in and out. Press Ctrl+Numpad 5 to recenter the camera.
  • View Pet status in the Pets app next to their name

Debug mode scripting:

  • ExecJS:foo - execute some JavaScript (this WILL break stuff, and we cannot provide support on this function, use at your own risk!)
  • SetSettings:Setting,Value - force player's Setting to a string value
  • SetSettingsInt:Setting,Value - force player's Setting to an integer value
  • DisableGroup:GroupName - disable an internal code group
  • EnableGroup:GroupName - enable an internal code group
  • DebugProgress - view player progression data in the dev tools window
  • Debug the HAP archive:
    • DebugArchive - view HAP archive data for the current capture in the dev tools window
    • WipeArchive - completely reset the HAP archive for the current capture
    • FillArchive - 100% complete the current capture's HAP archive
    • Open any HAP page, even if you have not visited it, by holding Shift and clicking on it


Join the community or sign in with your gaming account to join the conversation:

xk47 @xk47

Where is Export Character Data button located? No sign of it.