Introducing: Nuclear Throne Together

Perhaps you've already heard that I've been recently developing a mod for the current version of Nuclear Throne. And not "just" a mod, but quite an impressing one:

  • Adds Steam-based online multiplayer support to the game.
    That means invitations, public game list, and no port forwarding.
  • Replays
    Easily record and review your runs to learn from mistakes.
    Or even attempt to correct them by dropping into the game at any point of a replay.
  • Better coop
    Nuclear Throne never was a coop-centric game, and thus coop mode didn't receive enough attention, remaining ridden with various small bugs. This mod changes that, fixing pretty much every known issue, and giving coop some much-needed polish.
  • Bugfixes
    While fixing coop-related bugs is an obvious choice given the scope of the mod, I didn't stick to just that, and also fixed a handful of other issues with the game. Bugged "crown vaults"? Fixed. Game hanging in certain areas? Fixed. Occasional crashes during an intro to an important boss fight? Also fixed. The full list is long (200+ items) and available in the "readme" document.

So it works, it's nice, and you can download it right now.

Or continue reading on process and potential questions.

A bit of prehistory

In general, this mod's development followed a pattern commonly seen in my works:

  • 1. Pick A goal that is considered somewhat impossible, but does look possible to me.
  • 2. Slightly underestimate amount of effort required to accomplish the goal.
  • 3. Get it done anyway.

In this case, the following happened:

  • Needless to say, I do like Nuclear Throne a lot. I've sunk well over a hundred hours into the game over the course of it's development, watched the development closely, and was interested in the game's cooperative mode since it's introduction.
  • Last autumn, Wasteland Kings' (jam version of Nuclear Throne) source code became available through GameMaker-themed Humble Bundle deal together with a bunch of other nice games.
  • Overwhelmed by curiosity, I've decided to get the bundle and mess with coop games included for a little. This reuslted in Super Crate Box Together and Wasteland Kings Together mods.
  • WKT being well-received and working nicely for vast majority of players, numerous people suggested that Vlambeer should hire me to do online multiplayer for the actual game.
    In a brief chat following, Vlambeer's Rami Ismail voiced largely-reasonable concerns about whether the approaches used would be viable for NT.
    At the time I didn't feel like arguing about the fact that lack of online multiplayer means that many people won't get to play the game in coop at all, so I did not continue the conversation.
  • Sometime since the end of 2015, I was also looking at different bytecode implementations with intentions of looking for good tricks to use in my own bytecode interpreter.
    In part this also involve staring at GameMaker's bytecode format, partially for research, and partially for understanding how things work better. So I made a little tool (shown below) to display tweaked bytecode in the most readable format possible, did some tests, and sometime through this I've thought "well, this doesn't look that terrifying. If I were to tweak some things, could I hack some new code into a game?". And thus...

Deconstructing Nuclear Throne

The next thing that happens is me staring at a 9.5MB \ 233 000 line long bytecode dump of Nuclear Throne, trying to make any sense of what's going on, questioning my intentions.

Should you have an impression that reverse-engineering an existing large game to poke few thousand new lines worth of code into it isn't a bad idea – it very well is.

While for my purposes I would rarely need to actually decrypt snippets of bytecode (either adding new code or replacing snippets with something that would work with netplay), looking for anything in such a giant pile is, to say at least, not very fast.

So for the next long while I was poking this in spare time, concluding in a test mod release on May 21, 2016, and finally being able to get to the actual online multiplayer on May 26, 2016.

Small-scale netplay for a large-scale game

As you may know, Nuclear Throne gets pretty chaotic in late game.

While the game starts with singular enemies and a few projectiles here and there, in mere 10-15 minutes you can already have decades of enemies and hundreds of projectiles (many of which your own) at screen at once.

Obviously, you can't just send that much information on an average internet connection easily.

In this case, a feasible workaround is a "synchronous" \ "lockstep" - like system, where the game is modified to behave completely deterministically (as in, not depending on external factors), therefore reducing the volume of data to be sent to player actions.

Similar approaches are commonly used in emulation software, as well as most fighting games.

However, "synchronous" multiplayer also means input delay, which can hurt a little, particularly with mouse controls (ever tried playing something via TeamViewer\Nvidia GameStream? It hurts).

So the latency is divided between players, critical things (camera, aiming) are handled without delay, and there are additional tricks used to improve the situation where appropriate.

On the technical side, the mod uses Steam API via a native extension that I've made, which is how there are Steam invitations, lobby list, and other things that you'd expect to see in larger games;
As per usual, I made use of code from my existing projects, so certain menus and systems may appear very familiar.

All in all, while the mod requires somewhat-low-latency (100ms delay / 200ms ping) connection for comfortable play, that's already substantially better than needing the second player to come over.

Legal & extras

After having a buggy-but-functional build done after a week of work or so, came the exciting part: waiting for an answer at whether it is legal to release this mod at all.

See, being a likely-first mod of such kind, neither me nor Vlambeer folks could know for sure as to what is right (in legal terms) and what isn't. So I wrote to Rami. And Rami wrote to legal. And, well, this took a little longer than intended, having received the final answer almost 3 weeks later.

But that's okay, since waiting for the response also meant that the mod went through substantially more testing, and got proportionally more bugfixes, and even a few new features.

Perhaps somewhat unsurprisingly, NT having local-only coop meant that fewer people were playing coop at all, and as the result there were much more bugs in that than I've expected.

So I'd look at anything that was reported and could be traced back to anything particular easily.

Not having access to the original source code anyway, anything found to be related to a problem would be tossed out and replaced with a snippet based on freshly written code.

While this isn't an optimal approach, over time I was able to fix pretty much every known issue related to coop, as well as number of bugs from the original game.

For example, the aforementioned infamous "cursed vault" bug, which is basically the game accidentally mashing up two unrelated levels together (not to your advantage), turned out to be caused by the game accidentally dropping a chest onto an "objective" prop, crushing it, and triggering the level index change before the area was even done generating, as result filling the area with enemies and props from the new level.

In the end, the mod is now more stable than the actual game in some aspects, which is pleasing.

Could this be done better?

Of course.

It would have been nice to support up to 4 players, but, unfortunately, Nuclear Throne was not coded for 4-player support originally, so the game is lacking support for this in UI, code, and balance alike. While this might be doable in future, it would take time to get right.
Update: After an amount of technical struggles, I was able to implement this in spring 2017.

It would have been nice to have Mac and Linux versions, but that requires additional testing (and making variants of patcher program for Mac and Linux, which hurts a lot), so shall probably come in future. Till then, NT seems to run unusually fine on Wine.

Ideally, the mod should also have had even more going on for lag compensation, to make the game playable even on higher latency connections. Unfortunately, that requires reworking the game's collision systems to an extent, which would be a lot of trouble to do with how this works.

In an even more ideal scenario, it would have been great to integrate a scripting system into it, which, combined with online multiplayer, could quite likely longen the game's lifespan by a lot, but – alas, that is even more work. In fact, a pretty absurd amount of work for something that you aren't a developer of in the first place.
Update: Over autumn and winter of 2016 I managed to implement a suitable scripting system, culminating in February 2017 release. Later I managed to get Lua scripting to work in GameMaker, which is something you can make use of if you are looking to add modding support to your own games.

So you've got to do what is practical to do.

Could Vlambeer do this themselves?

This is something that some people were asking me about a lot.

In theory, with enough time, they could do an online multiplayer implementation by themselves.

In practice, the reality is kind of harsh, and while you can try to do online multiplayer without prior experience, you are incredibly likely to mess it up on first try.

By which I mean – if you are considering getting into netcode, please do not start with your commercial game. Things are easier to break than fix.

If you can, consider hiring someone that is actually proficient with this kind of thing.
Or at least seek existing tools/libraries that can help you with not messing up.

So overall while Vlambeer could have tried to do online multiplayer by themselves, it would likely be regrettable for everyone.

In conclusion

So, in conclusion, this was tough, and interesting, and fun.

This post should have been a tad bit longer, but I'm sure that everyone very much want to play it already, so that's it for now. page ThroneButt page

Related posts:

96 thoughts on “Introducing: Nuclear Throne Together

  1. Hi YAL, I’ve learnt a lot from you about Game Maker, keep up the good work.

    Have you ever thought of making a Multiplayer Engine on Marketplace, look at what you achieved so far with Nuclear Throne and Super Crate Box, I believe it could be a huge success.

    • I’m considering making a multiplayer engine asset time to time, but it’s hard to do something that would be both easy to use and sufficiently fail-proof. Releasing an asset only to answer endless questions about it wouldn’t be a great idea.

      GMNet is probably the best you can do in terms of a self-contained engine so far.

  2. Out of curiosity, how many hours of labor did it take you to undertake this project? If you had been commissioned to implement multiplayer, what kind of budget range should Vlambeer have expected? I understand that it will vary from project to project and that it’s dependent on many factors, so what about just for projects in the similar scope and size of NT?

    • I haven’t logged the hours on this mod (I guess I should’ve had), but it should be somewhere a hundred hours total as far as actual multiplayer and bugfixes go.

      Doing an “official” implementation could have been either faster or slower, since, on one hand, that would mean access to original source code (and ability to ask questions about it), but would also mean that quality standards would be higher. The result would have been better too, though.

      You are correct that this depends on many factors – game’s structure, scope, genre, even the engine used (e.g. Unity is less deterministic than GameMaker). Usually terms are to be worked out after carefully examining the project (mNDA intact) and doing some tests to determine what can be done and what would work good enough for the case.

      P.S.: Late response because my original reply got lost in spacetime without me noticing until now.

  3. I had an idea, would it be possible to add custom sprites, like as a C Skin? so someone could play as crystal, but have the sprite of a… Dinosaur or Melting with a sprite of Crystal or something

    Would that be possible?

    • You can do sprite mods on top of this mod, but you’ll have to unpack the file from the mod-assembled executable and pack it back after changing sprites in it. Shouldn’t be too much trouble but I’m not sure if anyone did get to writing documentation on this process yet.

      • I’ve Decompiled the thing and have tried recompiling it, and running Nuclear Throne, all of the sprites i modified don’t appear, so I look at the sprites themselves, and the custom sprites are there, so i recompiled it again and again and again, and no luck. Any help?

        • As I’ve mentioned, the NTT-specific gets packed right into the executable (nuclearthrone.exe), so you’ll need to extract it first.
          As of the current version (9830), it starts at byte offset 10 056 924 and goes on for 104 185 986 bytes. So you’d need to extract that file from executable, do whatever you must with it, and put it back in at the same position

  4. Pingback: Nuclear Throne Mod Adds Online Co-op | Rock, Paper, Shotgun

  5. Pingback: Nuclear Throne-mod lägger till online-co-op | Svenska PC Gamer

  6. No one ever mentioned that it removes all unlocked Crowns and Golden weapons, unlocks all the B skins, unprecedentedly gives easy access to Skeleton and Frog, gives you a color (that you can’t edit or do anything about) in solo, and least of all makes minor annoying changes to the settings menu.
    Aside from all of that, the fact that this is possible is amazing.

    • Which annoying changes to the settings menu? I don’t think I’ve touched that at all, aside of disabling it in online games due to silly implications of messing up other player’s settings;

      The mod uses a separate savegame and achievements, dailies, and weeklies are disabled in it. Everything is unlocked to avoid the trouble of transmitting the savegames over, merging them, and also not messing up the local savegame in process by adding remote player’s progress.

      • The minor changes to the Settings menu was that it used to be that when you right clicked to go back from one of the Settings sub-categories, it would send you to the Settings Menu; with the mod it sends you to the Main Menu. It’s really minor.
        Somewhat unrelatedly, is it possible to remove the mod and return to the same progress you had before installing the mod?

        • Oh, I had someone report that bit. While the mod should be acting the same as the base game in that aspect, it does manage to skip through multiple menus in that situation (button is pressed – audio menu is closed – settings menu opens – settings menu notices that the button is pressed – settings menu closes) for some reason. That’ll be fixed in the next public release.

          Indeed, for removing the mod you just remove the (new) “nuclearthrone” executable, and rename the backup executable (“nuclearthrone (timestamp)”) back to “nuclearthrone”. Or run the backup executable when needed. Future releases will work a little smarter to make it possible to name the mod executable differently (e.g. “nuclearthronetogether.exe”) and launch it as needed (currently this only works if adding a shortcut in Steam).

    • Or upon running the NTT Assemble either extracted or not, i get the message saying its malware and doesn’t extract or allow me to run it

      • Is that with “360 total security”? “HEUR” prefix stands for “heuristic”, which means that it considers that the executable could be doing something wrong. Which, I guess, is not entirely unreasonable (since the mod has to assemble a new executable from game files), but the particular antivirus flags executables with this left and right, down to larger ones like CS:GO.

        So you’d either whitelist NTT-Assemble, or just have anyone send you the reassembled ~100MB executable that it produces.

        • I updated windows defender and fixed this, but i have another question on the sprite editing thing

          So I edited the original and then installed NTT, upon booting up the game and jumping into the game with the custom and it sadly didnt work… any help?

          • reprhase the thing i said, How do i get the thing from the modded Nuclear throne?

          • The next public build will have a bit of additional tooling and documentation to help with that – basically you will be able to run NTT-Assemble with specific command-line argument to extract the file from the executable, and with another argument to assemble a new executable with a modified file inside.

  7. I’m rather glad and excited to see the sub-modding thing!
    Using the tool i’ve used before, i get several folders and such
    SPRT, AUDO, etc etc etc one of the folders is txtr, of whom which contains all of the sprites in the game, although extracting the i get no txtr folder, any help or should i use a different tool?

    • TXTR should definitely be in there, breakdown of “chunk” sizes in v9832 is
      STRG (136.09 KB), GEN8 (140 B), OPTN (64 B), SOND (46.95 KB), SPRT (1160.16 KB), BGND (196 B), SCPT (9280 B), FONT (9828 B), OBJT (256.95 KB), ROOM (1964 B), TPAG (248.22 KB), TXTR (3562.4 KB), AUDO (94.28 MB).
      Haven’t messed with the existing tools much so I’m not sure which work better. I recall that there were some guides on this on the NT modding subreddit though.

      Might add a command to export/import the PNG files directly later.

      • either that, or i have the txtr file modded beforehand in another folder, which i did import in there and thought it would work

        • Oh, you’ll have to do this separately, unfortunately, since I had to add a few new sprites and fonts (shifting things around), and also combined the sprites into one large texture sheet (instead of 4 smaller ones) in 9832 to have it play better with Wine.

  8. I got a problem. Everytime i get to the throne with my partner it kicks him out the game and it kicks me from his game

    • Use the /timeout command to increase the connection timeout; 9832 has a higher timeout value by default.

  9. Hey I have a problem. Whenever I try to host a game and invite someone or someone invites me, I try to join but it says connection_timeout… I could use some help.

  10. Now everytime i try to launch the mod it says
    action number 1
    of Create Event
    for object NetPlay:

    Steamworks extension could not load.
    Is Nuclear Throne path (…/steamapps/common/Nuclear Throne) void of non-English glyphs?
    called from – gml_Object_NetPlay_Create_0 (line 35)
    called from – gml_Object_MakeGame_Alarm_0 (line 6)

    Any help?

    • Seems like you might have mixed two versions of the mod – Steamworks.gml.dll files used in 9830 and 9832 are slightly different, and not compatible with each other. So I’d suggest that you reinstall the desired version, making sure that everything is copied over.

      • Yeah thanks its working now had to do a bit of fiddling with steam itself before it worked but using the older version worked, but may I ask whats the difference between the two?

        • I had to slightly change the function that is responsible for sending information, and all would seem well, but I didn’t foresee two things:
          1. Software used would not produce any reasonable errors with function signature not matching. It sees that the function in the DLL is different, and decides to just not call it.
          2. People are quick to “optimize” by not copying the seemingly-same file over even though it’s merely another 100KB worth of data and the readme says otherwise.
          In the best traditions, both of these were discovered after rolling out the public release, of course.

  11. When im playing with someone the fps drops and the internet is good. Is this the internet or a bug?

    • You can hold Tab to view the connection graph. If there are red spikes, that’s an issue with internet connection (the game has to “wait up” while a connection is choking).

  12. I’ve played with a friend and it was amazing.

    Would like to see an option to switch between the normal and the mod version since the original has other features 🙂

    • v9832+ can be safely renamed or moved to other directory, so long as you copy all the game files along.

  13. I’m curious if there is a way to play without the reviving (no need to revive teammates and once they die they are dead the rest of the game). Is this possible and just needs a lot of work to be done? Could I modify your mod to this myself? Nice job on the mod btw, very well done.

    • There’s /revmode hard in the current version, which will only revive the players when reaching the next loop. Other revival modes may also be of interest.

  14. Heey YAL,

    Thank for the great mod, it’s just awesome! 😀

    Two things that keep bothering me in-game are:
    1) Too small revive hitboxes. When you are playing and it is loop chaos, it’s quite possible that you miss the dead player and get killed because of it.
    2) Respawning without weapons. Same, if you respawn and don’t have your melee ready in loop chaos situations you are as good as dead. Also if another players dies and you go through a portal, the other player loses all his weapons.

    Good luck with this project, I’m very grateful for it and I think I’m not the only one 🙂


    • Characters will automatically pick up weapons on respawn if the weapons are anywhere near. Additional revival modes (see /revmode in documentation) offer various alternative options.

  15. I was messing around and i thought
    “Hey, what if Nuclear throne together had support to play as Yung Cuz?”
    Maybe it could be a secret command?

      • With 9832+, you can still run nuclearthrone-original executable to run the base game. Or rename the mod executable to be, say, “nuclearthrone-together”, and rename the original to be regular “nuclearthrone”.

  16. Pingback: Nuclear Throne Together v9838 – beam crossing, spectating, and other things

  17. How do you change the skin in co-op?
    Why can other people change the skin and I can’t?
    Why can other people cheat so they have different starting weapons?

    • Using mouse wheel (or weapon switch button). The included text document lists this and other little details.

  18. I’ve really been enjoying this mod but I think I have noticed a bug. In the base game Eye’s right-click/telekinesis moves weapons on the ground towards you, but it doesn’t seem to do that with this mod installed.

Leave a Reply

Your email address will not be published. Required fields are marked *