Getting Started Modding Hypnospace Outlaw

Basic modding guide for Hypnospace Outlaw

Posted by on


IMPORTANT NOTE TO MODDERS

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!

INTRO

Hypnospace Outlaw mods work by replacing content, and/or adding additional content. Mods have hierarchy determined by the player and whether a mod is a "Total Conversion" (TC) mod or not (more on that below). Mod content is loaded in order of top-to-bottom hierarchy with non-TC mods at the top, then TC mods, then finally default Hypnospace content at the bottom. Whichever mod is first found to include an asset is the one that is loaded, except for additive assets which instead build upon each other (more on that below). So for example, if the player has three mods installed, and all three replace the same image with their own version, the image would be replaced with the highest mod in the player-specified hierarchy that includes the image in question.

[SPOILER WARNING! IT'S RECOMMENDED YOU PLAY THROUGH THE ENTIRETY OF HYPNOSPACE BEFORE YOU DECIDE TO MOD IT]

Need help with your mod? Join our Discord community and check out the #hs_modding channel!


GENERAL RULES AND GUIDANCE

  • 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.

WHERE TO PUT MODS

The mods folder is located adjacent to Hypnospace Outlaw's save files, for example:

C:\Users\[Username]\Tendershoot\HypnOS\mods

If you are using portable mode, please put your mods in the saves\mods folder within Hypnospace Outlaw's root folder:

X:\ . . . \Hypnospace Outlaw\saves\mods

Make sure each mod is contained within its own folder, and that the mod's content folder(s) and config.ini file (more on that below) are located in the root of the mod folder, for example:

X:\ . . . \mods\Cool Mod\config.ini

MOD STRUCTURE

Hypnospace Outlaw's folder structure is set up like so:

|_Hypnospace Outlaw (root folder)
   |_HypnOS.exe
   |_data
      |_[content]

Your mod should follow this same structure, starting from the 'data' folder and matching the [content] path for whatever assets you are adding/replacing. For example, to create a mod that adds a Theme and Wallpaper to Hypnospace, your folder structure would be as follows:

|_Your Mod Title
   |_config.ini
   |_os
      |_themes
         |_your theme
            |_[images and theme ini files]
      |_wallpapers
         |_yourimage.png

Note: ONLY include folders in your mod files for which your mod has assets, you do NOT need to include a bunch of empty folders for everything in the game's data files :)

Mod configuration file (config.ini)

Within your mod's root folder must be a config.ini file. Here's the config file for the HypnOS 95 theme and wallpaper mod:

[ModConfig]
Title=HypnOS 95 Edition
Author=Cybertown Citizen Tubular2000
Date=1995-08-22
Version=1.0
Description={{Welcome to Merchantsoft's HypnOS 95 Edition!

Change your wallpaper and theme to 95Classic and 95Candy in the Settings -> Display menu.}} TotalC
InstallBeforeTutorial=1
InstallScript=AddWallpaper:95classic.png|AddWallpaper:95candy.png|LoadWallpaper:95candy.png|AddTheme:95Candy|AddTheme:95Classic|SwitchTheme:95Candy,1
UninstallScript=RemoveTheme:95candy|RemoveTheme:95classic|RemoveWallpaper:95classic.png|RemoveWallpaper:95candy.png|SwitchTheme:Default,1|LoadWallpaper:backgrounds_01b.png >

The ModConfig Group name and all Items under it are case sensitive!

  • [ModConfig] - Do not change this line
  • Title - Your game's title
  • Author - You!
  • Date - Release date of your mod
  • Version - Version number of your mod (recommend 1.0 or 1.0.0 format for consistency)
  • Description - A description of your mod. Wrap your text in {{tags}} if you want to include line breaks in your description. Keep it short!
  • TotalConversion - 0 or 1. Set to 1 to define your mod as a total conversion mod (more on that below)
  • InstallBeforeTutorial - 0 or 1. Set to 1 to force HypnOS to install the mod before the player completes the tutorial. This is not recommended if your mod uses Hypii, emails, or other HypnOS applications that the user does not have access to before completing the tutorial.
  • InstallScript - Using Hypnospace's proprietary scripting, write out any necessary scripts to run ONCE when your mod is initially installed. If InstallBeforeTutorial is set to 0, and the player has not yet completed the tutorial, this script will run as soon as the player completes the tutorial (or tosses it in the recycle bin).
  • UninstallScript - This script will run once when the mod is uninstalled
  • OnBootScript - This script runs every time the player starts the game, or immediately after the mod's InstallScript is run if it is not yet installed

Here's an empty config.ini file you can copy to quickly get started:

[ModConfig]
Title=
Author=
Date=
Version=
Description= TotalC
InstallScript=
UninstallScript=
OnBootScript

REPLACING/ADDING ASSETS

Now for the fun stuff!!!

Replacing default assets:

Almost all assets within Hypnospace's asset folders can be replaced by simply creating a folder structure and file(s) matching the asset you want to replace. For example, let's say I want to replace the Gooper gif you find in the fishbowl on Abby's page with an angel on a toilet:

  1. Create the folder structure for the gif asset:
    ...\My Cool Mod\images\gifs\gooper-3d-look\
  2. Add an image to the folder, or multiple if animated, and an "x.speed" file to define the speed of the animation (x frames per second):
    toiletgooper
  3. Test it! Run the game and install the mod by clicking the MODS button above your save file, then load your save file. Here's the result:
    toiletgooper2
    Beautiful.

Basically, if there's an asset in your mod folder with the same file path and name as an asset in the default Hypnospace data folder, it will be replaced with your asset.

Additive assets:

Some assets are what we define as "additive", and instead of replacing the asset they will instead add your content to the top of that file. These assets include, but may not be limited to:

  • emails.ini
  • chardata.hsd
  • progression.ini
  • chapters.ini
  • ads.ini
  • casefiles.ini

This is so that you can add additional emails, characters, progression logic, chapters, ads, and cases without completely overwriting the original data file. Note that if you add, for example, an email with the same name as an existing email in the default emails.ini file, YOUR email will take priority over the ORIGINAL email. In other words, even within additive assets the mod hierarchy rules persist. Please note that miscellaneous script files are NOT additive.

Adding new assets:

New assets can be added using the same rules as if you were replacing default assets, just use a new, unique folder/file name that doesn't already exist in the default files! For example, you can add a new webpage to a zone by adding the .hsp file to the following folder:

...\My Cool Mod\hs\04_teentopia\mycoolpage.hsp

If you want your page to be accessible in all three "normal" captures, remember to create copies for the hsa and hsb folders as well.

Special rules for some assets:

  1. Webpage images (i.e. those contained in the images\gif, static, shapes, and wordart folders) can NOT share the same name between folders - so for example, if there exists a static image named "foo.png", make sure you do NOT create a gif named "foo".
  2. All assets and folders MUST be lowercase!! You can refer to them using uppercase letters when downloading files, adding themes, etc, in-game, but the actual assets must be all lowercase.
  3. Soundscapes must be complete, including ALL sounds referenced in the INI and all variant sound files, even if you're just trying to replace a single sound file.
  4. Graphical Themes must be complete, including ALL assets found in the default theme folder, colortable.ini, and windowmargins.ini, even if you're just trying to replace a single image.

TOTAL CONVERSION MODS

Total Conversion (TC) mods act in a special way, in that instead of simply adding or replacing existing content, the files contained within a TC mod completely overwrite the game's default content. For example, if you were to create your own 'progression.ini' file (the file that dictates logic on game progression) and marked your mod as TC, your progression logic would completely overwrite the default logic shipped with the game. If you did NOT mark your mod as TC, your progression logic would instead be added to the default progression logic. In other words, files which are normally "additive" are instead completely overridden by the TC mod.

Some rules to TC mods:

  1. If your mod includes a zone folder matching the name of one of the default zones, only the pages within your mod's zone will be shown in-game.
  2. If your mod is a Total Conversion, and you're adding a new capture to the game, do NOT use the prefix 'ex' for the capture folder.
  3. The default capture MUST be "hs"! If you only have one capture in your mod, make it 'hs'.
  4. If your mod includes captures you'd like included in the HAP total percentage DIFFERENT THAN hs and hsa and hsb, run this script in your mod's InstallScript: SetTotalPctCaptures:hs|hsa|hsb replacing "hs|hsa|hsb" with your captures' folder titles separated by a pipe | character.
  5. The prize for getting 100% Total HAP is modable by creating your own 'misc\archive100.txt' script file

PREPARING AND UPLOADING YOUR MOD

Compress your mod within a .zip file. Please DO NOT use .rar, .7Z, etc, as the in-game mod browser only supports .zip. Do not put your mod's root folder more than one folder deep. Please structure your zip like the following example:

|_YourMod.zip
   |_Your Mod Title
      |_config.ini
      |_[folder]
         |_[subfolders and content]

Create a mod entry and upload your zip file here: Hypnospace.mod.io


Comments

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