This is a FAQ for Nuclear Throne Together by YellowAfterlife. A most-up-to-date version of this FAQ can be found online. If you want to use search (Ctrl+F), make sure to set display to Everything first.

Click on sections to expand/collapse them.
Quick display controls: Categories · Sections · Everything ·

Setting up
Installing NTT
  1. Right-click Nuclear Throne in your Steam library, pick Properties - Local Files - Browse local files.
  2. Extract the NTT archive into the Nuclear Throne' directory.
  3. Run "NTT-Assemble" executable, pick 1 (Install) to assemble a NTT executable.

    If you get a "can't find assets in data.win" error, remove the [probably leftover] data.win file from game directory and retry.

    If all is well, a NuclearThroneTogether executable will appear and you'll be able to run the mod from it (and/or add it as a shortcut to your Steam/etc. library).

The mod is told apart from the base game by the fact that it displays the version+notice at the top of main menu.

Uninstalling NTT
  1. Right-click Nuclear Throne in your Steam library, pick Properties - Local Files - Browse local files.
  2. Remove the (modified) NuclearThrone.exe.
  3. Rename NuclearThrone-(datetime).exe back to NuclearThrone.exe.

    If you have installed NTT multiple times, the earliest-dated NuclearThrone.exe will be the base game, while the rest will be older NTT versions.

If all is well, the game will no longer display a version notice on the main menu.

Alternatively, if you've installed mod on Steam, you can just "verify cache".

Updating NTT

When a Nuclear Throne Together update comes out, a notice is shown on top of the main menu.

Installing the update is a matter of downloading the new version and installing it on top of existing one - you do not have to uninstall the old version prior.

Supported game versions

The mod was confirmed to work with the following versions of the game:

  • Steam u98 / u99
  • Humble u98 / u99
  • GOG u98 / u99

The mod will not work if installed on top of older versions of the game or other mods (majority of which are based on u19).

"Couldn't find steam_api.dll"

If you are using a DRM-free version of the game and get a "couldn't find steam_api.dll" error upon running, toss literally any (even non-functional) steam_api.dll into the game directory so that it can fail to load it and move on.

"NTT-Assemble is not a valid Win32 application"

On select machines running Windows XP, NTT-Assemble simply ceases to launch for unidentified reason.

The solution is usually to use a machine running a newer version of Windows (or sending someone the files) to patch the game files, moving them back afterwards.

"NTT-Assemble is a virus"

It can occur that certain versions of certain antivirus programs can consider NTT-Assemble (mod's patcher program) to be a virus. This is a false positive, supposedly caused due to suspicion arising from the fact that program copies parts of game' executable to assemble a new one. In case that happens for you, there's a bunch of ways you can resolve this:

  • Try updating the "virus definitions" in the antivirus program.
  • "Whitelist" the file in the antivirus program so that it lets you run it.

    NTT-Assemble can be removed once it assembles the new NuclearThrone executable - the mod does not need it to function.

  • Have someone send you the resulting NuclearThrone executable (~110MB).

    The modified game executable is never considered a virus.

  • Run NTT-Assemble in a sandboxed environment (e.g. Sandboxie) and copy back the resulting executable (for same reasons as above).
  • Compile NTT-Assemble by yourself from the source code to be sure (requires Visual Studio and basic understanding of it).
On Mac/Linux support

Re-writing this section 4 years after NTT's initial release, it seems unlikely that NTT will be available on Mac/Linux too soon, if ever.

Initial issues with getting cross-platform multiplayer to work has been since accompanied by a number of native extensions (such as for loading shaders) that are Windows-only, 32-bit/64-bit differences, and increasingly nightmarish changes to Mac signing requirements.

The mod does work alright under WINE/CrossOver though.

Game-related
Game runs slowly

Restart Steam and re-run the game.

It can occur for Steam API (which the mod makes heavier use of) to get "stuck" and take increasingly longer to respond.
Restarting Steam fixes the issue.

Game runs at double speed

Remove options.ini and restart the game.

If that does not help, re-extract options.ini from the archive, open it in Notepad (or equivalent) and change

AlternateSyncMethod=0

to

AlternateSyncMethod=1

before restarting the game again.

Blank screen on start

It can occur that upon booting the game will appear completely black (or white).

The first step in this case is to press Alt+Enter to exit full-screen mode.

If the game window is still blank (but is making sounds), you may have to update your
graphics drivers or try setting the game to run in Windows XP compatibility mode.

Otherwise, you can try opening options.ini and changing

VertexBufferMethod=1

to

VertexBufferMethod=2

before restarting the game.

Migrating save files

Nuclear Throne Together uses a compatible save format but a different file name.

Versions 9900+ will automatically make a copy of base game's save for use with NTT.

If you want to copy files manually, you can do so by navigating into the save directory
(%LOCALAPPDATA%/nuclearthrone on Windows) or using chat commands, e.g.

/loadgame NuclearThrone.sav
/savegame NuclearThroneTogether.sav

to import a save file from NT to NTT, or

/loadgame NuclearThroneTogether.sav
/savegame NuclearThrone.sav

to export a save file from NTT to NT.

Dailies/weeklies

Dailies/weeklies currently are not available in NTT for technical reasons - scoreboards are hosted on ThroneButt, which does not support separating scores by game version (or fact of NTT use, in this case).

As the result, it is not possible to implement these without disrupting the normal scores (level generation does not match up anymore) or reworking TB's backend just for this purpose (a process that could take weeks).

Therefore, while these may be implemented in future, it is a sizeable task that depends on multiple people dedicating large amounts of their time to it, so you can only be patient.

Using gamepads

If the game does not automatically recognize your gamepad, not all hope is lost - you can use the /gamepad commands to point it to the right device explicitly. This also allows to have input devices in a different order (e.g. P1 on gamepad and P2 on keyboard+mouse).

Using custom aspect ratios

If you are trying to play the game with more than 2 local players, default screen size might be a little too small. Fortunately, starting with v9900, this can be changed via a modding function called game_set_size(width, height).

So if you have 4 players and a standard FullHD screen, you could, for instance, do

/gml game_set_size(426, 240)

which would give just enough space for the additional HUDs to reside in.

If you are making total conversion mods, you may also find this to be useful.

While the game will do it's best to function at different sizes, keep in mind that this affects the balance (and "on-screen" checks), and is not how the game intended to be played.

You can always "add back" some difficulty with mods though.

Using custom framerates

In NTT 9940+ you may adjust the game to run at arbitrary framerate, like so:

/gml room_speed = 60; current_time_scale = 30 / room_speed;

(you can change 60 to your desired frmaerate)

Combined with "native cursor" and "pixel mode" options, this can make the game feel incredibly smooth.

Revival modes

Revival behaviour can be changed via /revmode command.

Character-specific ultra mutations

Ultra mutations mode can be switched between coop-only, default-only, or both via /ultras command.

PvP mode

NTT does not come with a separate PvP mode out of box for the vast possibility of options that can go into such mode.

It does, however, provide the means for mods to implement such a feature, and at least one mod of such kind already exists.

Loading mods
Making mods
Online-related
Playing via Steam

If you own NT on Steam, NTT will default to using Steam for online features.

That means that upon clicking "coop" you will be presented with a list of public lobbies (if any), and in-lobbby UI will spot a "invite friends" button that opens Steam invitation overlay.
No port forwarding is required and things are generally very nice.

On an occasion the game may fail to connect, but this is resolved by trying to connect again in a few seconds.

Playing without Steam

If you are using a DRM-free version of the game (or want to play over LAN),

  • If you are running from Steam, you will need to disable it in "coop" menu.
  • "Host" option opens a server on the specified UDP port.

    If you are not playing over LAN (or LAN simulation software such as Hamachi, Radmin VPN, or many more), port forwarding is required.

  • "Join" option attempts to connect to the given IP-port.

    For non-local play you'll need to know the person's external IP.

  • For non-local play, playing with more than 2 people may not always work as expected due to how connectivity works.
Troubleshooting lag

Short-term "freezes" in online mode are usually caused by quality of internet connection.
In short, if the connection of either of players lags, the game waits up for a player to "catch up".

The "delay" setting in lobby (and /delay command in-game) declares both the input latency, and a measure of "just how much" the internet connection can lag before the game will have to pause and wait.

By default, the game will attempt to pick the optimal delay automatically, but you can also change it manually to find the optimal balance. Watching the latency in statistic overlay (Tab) may help.

Mid-game timeouts

As mentioned above, if there's nothing from the player, the game waits.

If there's no response from the player for a period of time (15 seconds by default), the connection is considered to be dead and is dropped.

If you are playing with someone that has periodic connection issues, you can use the /timeout command to have the game wait for them to respond for longer.

Desyncs

Since the mod is fairly experimental (to say at least), you may sometimes encounter issues such as desyncs. A desync is a situation where the game state gets out of symmetry to the point where the game is not able to recover automatically. Connection is dropped in such case.

If you were playing without any mods loaded, see if you can replicate the issue with /tracksync option enabled, and post copies of related directories from "desyncs" subdirectory (%LOCALAPPDATA%/nuclearthrone/desyncs on Windows) to allow troubleshooting the issue.

When these occur while playing with sub-mods, chances are that the issue is with logic in one of them, in which case you would contact the mod author to see about investigating the issue.

Configuration file format

This section details the format of NuclearThroneTogether.ini in the game's save directory.

Sections correspond to INI sections, like

[Colors]
0=#FF0000
[Visual]
VSync=1

Minimum NTT version is specified where appropriate.
If it isn't, it is probably supported since at least v9921.
Base game uses NuclearThrone.ini and 99r1 is on par with v9921.
For practical reasons, only options of any remote interest are listed here.

Colors
Visual
WeaponTooltips=17

Tooltip delay when mouseovering a weapon in HUD.

MutationTooltips=17

Tooltip delay when mouseovering a mutation in HUD.

PortalFx=1

Whether portals should be drawn on level transitions and alike.

VSync=0

If set to 1, forces vertical synchronization.

Removes tearing but causes freeze frames and small lag to be stranger.

Since v9925.

HideMaxText=0

If set to 1, hides "Max <ammo type>!" popups.

Since 9925.

SinglePlayerCursorColor=

If set to a color, overrides the cursor color in menus and single-player.

The base game essentially treats it as

SinglePlayerCursorColor=#ffffff
Subpixel=0

Whether to use non-standard display scaling. Options are:

  • 0: Normal scale (1x)
  • 1: Fractional scale (can introduce seams)
  • 2, 3, ..: 2x, 3x, etc. integer scale.

Accessible via the options menu in NTT.

Autopause=1

Whether to pause when the game window loses focus.

Accessible via the options menu in NTT.

Controls
KeyboardDirect=0

If set to 1, the game uses GetAsyncKeyState to poll keyboard inputs.

This can help with keys getting stuck upon switching windows.

Since NTT v9925.

KeyboardClear=0

Clears the keyboard inputs upon switching back to the game window.

Originally added in attempt to figure out a workaround for someone getting keys stuck permanently, but had no apparent effect.

Since NTT v9925.

KeyboardExtras=1

If set to 0, disables various key aliases that are not remappable.


The following take key names as per this post; If KeyboardDirect is set, you can use raw virtual key codes. In NTT<=9936 they only take lowercase key names. In NTT>=9937 you can also use mouseLeft, mouseRight, mouseMiddle, mouseWheelDown, mouseWheelUp.

KeyboardPaus=esc

Sets the button used to pause the game.

KeyboardOkay=enter

Sets the button used to confirm selection in menus that support keyboard navigation.

KeyboardExit=esc

Sets the button used to back out of the menus / unpause the game.

KeyboardHorn=b

Sets the button used for airhorn.

KeyboardKey1=d1 .. KeyboardKey9=d9

Sets bindings for the digit keys. These can be used as custom keys by mods.


GamepadDeadzone=0.3

Changes gamepad analog stick deadzones for movement.

Valid range is 0..1.

Set via /gpdeadzone in NTT.

GamepadVibration=1.0

Changes gamepad vibration amplitude multiplier.

Valid range is 0..1.

GamepadNormalize=0

If set to 1, remaps analog stick readings from square (diagonal input produces X=1,Y=1) to circle (diagional input produces X=0.7,Y=0.7).

Set via /gpnormalize in NTT.

GamepadExponent=1

Can be set to values slightly higher or slightly lower than 1 to calibrate gamepads with unusual sensitivity.

Set via /gpexponent in NTT.

Gamepad0=0

First gamepad index (P1 with gamepad on, P2 with gamepad off).

XInput gamepads use indexes 0..3, DirectInput use 4..11.

In NTT this is set via /gamepad.

Gamepad1=1

Second gamepad index (P2 with gamepad on).

XInput gamepads use indexes 0..3, DirectInput use 4..11.

In NTT this is set via /gamepad2.

GamepadHorn=

Allows to set an airhorn button for gamepad controls

Supported values are face1..face4, rb, rt, lb, lt, back, start, ls (left stick click), rs (right stick click).

Chat commands
On chat in general

Chat is opened by pressing T.

Commands are entered as messages starting with slash /.

Not all commands work everywhere - you'll be notified if you can't use something.

Local commands

These can be used wherever and relate to what applies only on your machine.

/help

Displays a complete list of available commands, split by category.

/outlines

Toggles colored outlines around the characters.

This makes it easier to notice the characters among the action and to tell who is who
if multiple players use the same character.

/wscale <factor>

Changes window size to an integer factor.

For example, /wscale 2 will make the game window at 2x of screen size
(~640x480 on default resolution).

Due to how the game works, this generally looks better than resizing manually.

This option is memorized between launches.

/wtips <delay>

Changes the time (in frames) that you need to mouseover a weapon in HUD for before it's name would be displayed,
e.g. /wtips 30 for 30 frames / 1 second. Set to -1 to never display.

/mtips <delay>

Changes the time (in frames) that you need to mouseover a mutation in HUD for before
it's name and description would be displayed,
e.g. /mtips 30 for 30 frames / 1 second. Set to -1 to never display.

/portalfx

Toggles portal effects. Default is on.

Consider disabling if the framerate drops noticeably during level generation.

Particularly useful if running in higher resolution and/or under WINE.

/mouselock

Toggles mouselock. If enabled, mouse will not be able to leave the game window while it's in focus. Particularly handy for running the game in windowed mode or on multi-monitor setups.

Equivalent to the option in Settings menu.

/nativecursor

Switches between native cursor modes.

This option eliminates cursor lag by using system-level functionality.

Equivalent to the option in Settings menu.

/subpixel <factor>

Changes native scaling mode. Factor can either be a number
(1 for default, 2. for 2x, etc.), or 0 for native scale.

Equivalent to the option in Settings menu.

/stopaudio

Halts all currently playing sounds. Is for cases when a looping sound gets stuck.

/stdout

Toggles sending of chat messages to stdout (default off).

That is, if you run NTT from command-line/terminal/Powershell, with this enabled
you can observe the send messages even if the game itself softlocks.

Intended for debugging issues with mods.

/exit

Instantly quits to the main menu.

This allows to leave online games without having to return to character select screen,
as well as being handy for replays and spectating sessions.

Session commands

The following apply to the current session (since pressing Play/Start).

/timeout <time>

Changes how long the game should wait before considering the connection to player(s)
to be dead. Time is in seconds.

/tracksync

Toggles additional debug information for desyncs.

This may have negative effects on framerate, but provides far more information in desync dumps for debugging the issue(s).

/delay <latency>

Changes the input delay (see Troubleshooting lag).

Only the game's host can use this command.

Time is in milliseconds, e.g. /delay 100 for 100ms latency.

/sepview

Toggles separated views in online sessions (on by default).

Some people argued that the fact of players having separated views in online sessions
impacts the balance, and thus this option was added to revert to local coop like
behaviour at will.

/hardmode

Toggles hardmode (for the lack of menu option).

/revmode <option>

Changes revival rules in coop sessions. The possible options are:

  • default: normal NT behaviour - revival markers and health drain if the players take too long to revive their parthner(s).
  • soft: for novice players - revival markers, but no health drain.
  • hard: for veteran players - revival is automatic but once per loop (on 1-1).
  • legacy: pre-u90 behaviour - players are revived by finding a health chest.

Since the option affects the game, all players must vote for a new option for it to be changed.

/ultras <option>

Changes ultra mutations mode in coop sessions. The possible options are:

  • coop: normal NT behaviour - only coop ultra mutations (shared health/shared ammo)
  • own: only character-specific ultra mutations.

    If multiple players used the same character, ultra mutation is shared (either applies to each of them or is stacked accordingly).

  • all: both coop and character-specific ultra mutations.

    Coop ultra mutations are offered at the first round and disable character-specific picks for the remaining players.

Since the option affects the game, all players must vote for a new option for it to be changed.

/ccrown <crown name>

Changes the starting crown, e.g. /ccrown blood.

For custom crowns, file name (some for some.crown.gml) is used.

Use /ccrown none to reset.

/cwep <weapon name>

Changes the starting weapon. Accepts both weapon names (golden machinegun) and weapon IDs.

For custom weapons, either full weapon name or file name can be used.

Use /cwep -1 to revert to default weapon.

If you have multiple local players, /cwep2../cwep4 are to be used for them.

/bwep <weapon name>

Much like /cwep, but changes the secondary slot starting weapon.

If you have multiple local players, /bwep2../bwep4 are to be used for them.

/pwep <weapon name>

Much like /cwep, but contents of proto chest (for challenges).

/loadgame <path>

Loads the save file from specified path.

Intended for maintaining progress in online sessions.

Note that this disables auto-save so you'll need to use
/savegame for saving the modified file if you need to.

/savegame <path>

Saves the current unlocks into the given file.

(is to be used with /loadgame).

/color <color name>

Changes the color used by the local player.

Affects healthbar color, cursor color, and outline color.

If you have multiple local players, /color2../color4 are to be used for them.

/gamepad <gamepad number>

Changes the gamepad used for the local player.

The options are:

  • 0: Use keyboard+mouse
  • 1..4: XInput gamepads
  • 5..12: DirectInput gamepads

If you have multiple local players, /gamepad2../gamepad4 commands are to be used for them.

/die

Kills the character(s) controlled by you.

Only intended for use if you somehow get stuck.

Modding commands
/sideloading

Votes for enabling mod-related commands.

All players must agree for the option to be enabled.

/load <command file path>

Runs all commands from the given file.

If the path points to a directory, will attempt to run a main.txt or main.cfg file in it.

The commands are ran relative to the directory containing the file, meaning that they do not need to include relative paths to it.

This command is also available under /loadtext and /loadconf alias.

/loadsprite <sprite name> <image path>

Replaces the given sprite with file's contents.

Files should reside in "images" subdirectory of the game.

File names can have _stripN or [N] suffix to denote the number of frames included. For list of modifiable sprites, see NTT-Sprites.html.

/loadimage <sprite name> <frame index> <image path>

Akin to /loadsprite, but replaces only the given frame of a sprite.

Good for making sprite mods that work with other sprite mods.

/unloadsprite <sprite name>

Restores the given sprite to the original form.

/savesprite <sprite name> <file name>

Saves the given sprite into "images" subdirectory.

File name can be omitted to have it defined automatically

/saveimage <sprite name> <frame index> <file name>

Akin to /savesprite, but only saves the given frame from a sprite.

/copysprite <source sprite name> <target sprite name>

Copies contents of one existing sprite to another.

This does not result in any image data being transmitted\stored.

Can be followed with multiple names of sprites to copy to.

/copyimage <source sprite> <source frame> <target sprite> <target frame>

Copies a particular frame from one sprite to another.

Akin to /copysprite; can have trailing pairs of sprites and frame indexes.

/loadmod <path>

Loads a GML mod from the given path. Specifying .gml / .mod.gml suffix is optional.

/loadrace <path>

Alias for /loadmod with .race suffix.

/loadwep <path>

Alias for /loadmod with .weapon suffix.

/loadcrown <path>

Alias for /loadmod with .crown suffix.

/loadskin <path>

Alias for /loadmod with .skin suffix.

/loadlive <path>

Same as /loadmod but will also automatically reload the mod whenever it changes.

/unloadmod <path>

Unloads a GML mod with the given path.

/silencemod <path>

Disables chat output (trace() calls) from the given mod.

/ignoremod <path>

Disables error output from the given mod.

/gml <code>

Executes a snippet of GML. Good for quick testing.

Will display the result if there's a return-value.

Can be used as /gml =[code] as an alias to /gml return [code].

/gmlapi

Dumps a list of available functions, variables, and constants into api.gml file.

inside the game's data folder (where the savefile and "images" directory are)

/locate <object name>

A small shortcut to quickly display positions of all instances of the given type.