Jump to content

Unofficial Modding Guide


Recommended Posts

Hey there, today we've released the starting pages of a new Modding Guide to the public.

Currently it's a basic 'how to get started' tutorial, but as the time goes on we'll add more examples and advanced concepts.

Note that the has been updated to the mergedown changes. We no longer provide pre-mergedown information, and we suggest not supporting legacy vanilla for new mods and just waiting for the mergedown to complete in a few weeks.

Link to the Guide: https://github.com/Cairath/Oxygen-Not-Included-Modding/wiki

 

The guide is currently maintained by @CynicalBusiness and myself. Feedback is appreciated.

 

Edited by Cairath
  • Like 5
  • Thanks 10
Link to comment
Share on other sites

Very nice work - thanks!

Used this today to get a dev environment up and running, no issues at all with the content in the Intro or Publishing sections. Some of the steps could use a little clarification (VS instructions, UI labels, a typo or two), I'll create another project in VS tomorrow and make some notes.

Also used examples from your stellar repo to get my first mod working - planning to post it soon!

  • Like 1
Link to comment
Share on other sites

Hi Cairath,

I hope the guide suggest modders to use 'Release' compile instead 'Debug' compile on ready upload mods, it might be sound unnecessary but when pile it on it will cause noticeable performance between 'Release' compile and 'Debug' compile.

Link to comment
Share on other sites

I read one of these guides at one point that said we were targeting .net 3.5 which is great since I have VS2008, but when I come to setup my environment I'm told I can't use Assembly-CSharp or Assembly-CSharp-firstpass references because "This assembly is built by a runtime newer than the currently loaded runtime and cannot be loaded."

I see .net 4.0 is specified by your guide- did it change to 4.0 so now it's impossible for me to make mods with Visual Studio 2008? :<

 

*edit (followup question): might it be possible for Klei or anyone to create a standalone compiler for us? So we can still create code and compile it for ONI mods even if we don't have the environment? Previously I've played with mods for Klei games and all I needed was a text editor if I remember right- the idea of finding/buying a newer version of Visual Studio just to mod isn't so lovely since they stopped coming with Crystal Reports and stuff..

Edited by outseeker
Link to comment
Share on other sites

ok, immediate developments have uh developed lol

we can now download visual studio directly from Microsoft and completely free.. there has to be some sort of catch! VS2019 is the current version:

https://visualstudio.microsoft.com/free-developer-offers/ - I'm installing it rn, and if it's not a dumpster fire my question can be considered irrelevant :)

update: works fine, i'm modding ^_^ thx dont mind me!

Edited by outseeker
all good
Link to comment
Share on other sites

9 hours ago, Cairath said:

There is no catch - Visual Studio Community is free for non-commercial use.

Then one little advice: If you just make ONI-mods with it = okay. If you have a patreon link or something else you may get money from users... you may be using it in a commercial fashion, depending on the rules in your country.

Link to comment
Share on other sites

41 minutes ago, SharraShimada said:

Then one little advice: If you just make ONI-mods with it = okay. If you have a patreon link or something else you may get money from users... you may be using it in a commercial fashion, depending on the rules in your country.

Incorrect. For individual users it's free even if the app brings money. It's even alright in small companies. Patreon links and donations absolutely do not exempt you from free use as an individual.

  • Like 1
Link to comment
Share on other sites

Looking through the guide, even at a glance it's apparent that it's... if not incomplete, as such, then very barebones. It tells you how to set up the programming environment and a few best practices regarding directory structure, and lists advice for distribution, but it doesn't discuss the existing directory structure or any of the internal standards, or how to alter, avert, or make use of them. I understand that Klei insists there is no API, but that doesn't change that there is an existing core structure to the vanilla base. Off the top of my head, improvements to this guide would involve documenting that standard structure, including some of the important segments and practices within the code (where does X go, what do they use to call Y, what is the internal syntax for Z), the formats and limitations required for graphics, the formats and limitations required for audio, and the key data to allow custom additions to interact with the base game.

One modder may simply want to change a few names or the fonts used - Your guide should tell us either where this data sits, or how to find it ourselves.

One modder may want to change how something already in the game looks by altering or replacing a static image - Your guide should tell us where to find all the images, how to find the correct image, how to call the new image, and what we need to know about making the new image.

One modder may want to change how an entity moves or behaves algorithmically - Is the code for that in one place or several places and how do we find that to base our changes on it?

One modder may want to add something entirely new that uses connected tiles or animations - We need to know where to look, what to do, and what not to touch.

Modding is intricate, methodical work that can be complex or simple, but the actual difficulty of it depends on the available information and how it's organized and presented. As a staple veteran of the community and a programmer with so many successful mods under your belt, you have a unique view into what's necessary to make any number of different types of mods come to fruition, and you've shown a willingness to write not just any instructional guide but one which informs your peers of their options and of risks to avoid. Work with that.

Best Practices, like using the versioning system to maintain current, past, and working releases as recommended by fatheroctopus or formatting your mod for later translation as described by cheerio and more recently by akiart, should be included, and credited where appropriate.

Special aides like Tools Not Included should be mentioned and their common purposes in modding summarized.

We have mods that add dupe templates, remove dupe templates, add traits, remove traits, add buildings, remove buildings, restore older versions of buildings. We have mods that add and remove storage limits and death conditions and available directions of movement. We have mods that automatically add new schedules from custom templates, that change how fast we can speed the game, that alter how we can use the camera.

We have a proposal for a mod to add a functional calendar system, with people comparing it to what already exists and saying it would need to first make the game track the cycles passed - but it already does that, so we just need to know where. We have mods that track how many of this or that are active or in storage, and proposals for mods that track things not yet tracked. We have mods that let buildings pass behind eachother, mods that DON'T let buildings pass behind eachother, mods that allow them to connect, mods that FORBID them to connect.

With the right information properly documented and presented, some of the most complex mods we can think of can become relatively easy to actually make, especially by a skilled developer. Without the supporting information, even simple mods can be made incredibly difficult, especially for beginners.

I'm sure there are important examples and development facets I've not presented or even considered that apply to ONI mods that your experience and presence have exposed you to, as well.

  • Like 1
  • Big Ups 1
Link to comment
Share on other sites

The guide is very much a work in progress, however what you're expecting is extremely unrealistic. As you already know, there is no API and it's not feasible to document every single class and "how to find font X" or "how to find image Y". I'd be writing a book.

There will be more examples of common template-able things as well as contributions, however real life took over and it had to be put on hold. 

At current, the guide serves as a starting point and directs people to our modding discord where we have linked repos of more advanced modders for examples as well and more resources. While possibly useless to you, it's been doing its job helping people to get started (both professionals and not). More will come, but I won't promise a timeline. We have a very long TODO list (and yes, contributions from folks like Aki are on it) but decided to release the starting point when it was ready, since people were using outdated/incorrect guides and encountering problems before they even started.

 

12 hours ago, Claws61821 said:

Special aides like Tools Not Included should be mentioned and their common purposes in modding summarized.

Do you know what TNI is? It's not a modding tool.

 

TLDR: There will be more, but life comes first and it's been busy. But it'll never be a complete documentation of every single class in the game.

  • Like 4
Link to comment
Share on other sites

You misunderstand me, although I can if I'm generous see why. I don't want anyone (except maybe Klei's developers) to document "every single class" and explicitly where/how to find each individual font and image. What I was suggested was the most important classes and methods, and the common techniques to find the rest (besides the obvious). You, having published more than thirty individual mods yourself, know far better what those would be than I or most others here. The examples which I listed were meant only to fuel your thought process, and that because the guide hasn't been updated in more than six months and you specifically requested feedback here in your opening post.

I understand the realities of an iterative document, and I understand the realities of life getting in the way of secondary and tertiary priorities. You'll note that I was polite enough not to make mention of those delays before you yourself did. That being said, there has been neither progress on the public-facing form of the document nor any report there or in this thread of those delays and their cause, so it's rather facetious to expect people arriving from the forum to just know that it hasn't been updated in so long and why, and that there's been any work done in the background that we just can't see.

When someone looks up a guide for modding a game or software suite, they expect from experience elsewhere something that covers the basics of how to alter that particular software and footnotes on where to find more information with the assumption being that the guide should make that unnecessary unless the end-goal is something unusual or difficult or unusually complicated, and maybe a recognition that the guide itself is incomplete and under development if appropriate. It may be inconsiderate or malapropos of them, but what they certainly don't expect is a document that tells them only how to set up the required programming environment and strongly pressures them to visit chat rooms for anything more than that or else stumble clumsily through everything alone.

Most tools used in modding anything aren't specifically intended as modding tools. I perfectly understand that TNI is "simply" a reference tool, but I'm not arrogant enough to discount that it might have uses in the development process entirely out of hand. It was given as an example not because I expected any particular uses for it specifically but because I didn't know if there weren't any and because I was certain there are tools commonly used in modding ONI specifically that weren't yet described in your guide.

 

TLDR: People can be patient when they know what's going on, but save the smug for when you haven't openly requested advice and don't twist their words when you reply.

  • Like 1
Link to comment
Share on other sites

Hopping back in to this thread - I just re-enabled a very basic mod that I wrote with the help of this guide in February 2020 and it works just fine, woohoo! My plan is to expand it a bit with an eye on DLC and new materials/research/recipes/equipment and release it in 2021.

Thanks (again) for taking the initiative on this project, having the resources to make small additions or adjustments to this game has added a huge amount of enjoyment for me!

I actually have the free time to do some writing (both for humans and for computers) - I'll step through the guide again (no difficulties with the last attempt at getting a simple mod installed and working) and drop some feedback either here or on Github.

Cheers!

Link to comment
Share on other sites

Hi, I'd like to start modding, but I saw that you recommend decompiling.  Why not just publish your symbols somewhere and I can skip that step?  If you aren't obfuscating your code then there should be little concern of publishing them.

I'd also like a small high level overview of the architecture / organization.  The same spiel you'd give to a newly hired engineer.

It would be also nice to have a few sample trivial mods in the vein of changing text / color, new component, etc.  Any architecture pitfalls / known challenges would be good to know too like "this area of code will change a lot w/new DLC", etc.

 

  • Big Ups 1
Link to comment
Share on other sites

followed the guide..got all the downloads then started to decompile and read trough all the .dlls i could suscribe to. to assemble a portrait of similitudes...i got my binary bases out of the cupboard and ive learned many many things and still learning of course i hope to be able to dp my first simple mod this year.

i appreciate the guide alot it would be very nice that someone from klei gives a hand to update/document because if you ask 3/4 the players prefer play the game instead of learning code or use the rest of the time with their family. This guide was not a simple task at all.

but it could use more.of course.

have a nice cycle ;)

Link to comment
Share on other sites

On 1/4/2021 at 1:40 PM, boiledDupe said:

I'd also like a small high level overview of the architecture / organization.  The same spiel you'd give to a newly hired engineer.

It would be also nice to have a few sample trivial mods in the vein of changing text / color, new component, etc.  Any architecture pitfalls / known challenges would be good to know too like "this area of code will change a lot w/new DLC", etc.

I would enjoy having the same!

On another note, I made a very simple mod with the help of the guide and the work of @Cairath ...about a year ago, it added a recipe to an existing building.

It worked before I activated the DLC, let me see if I can dust off Visual Studio and get it operational...I think it will serve as a decent working example for someone to at least get the modding system working on their local installation.

As for the architecture, perhaps I can connect with the Klei team...has anyone from the community done this before?

Link to comment
Share on other sites

On 1/4/2021 at 11:40 AM, boiledDupe said:

Hi, I'd like to start modding, but I saw that you recommend decompiling.  Why not just publish your symbols somewhere and I can skip that step?  If you aren't obfuscating your code then there should be little concern of publishing them.

Because that would be redistributing game files and is illegal.  It'd also mean that you have to keep files updated from another download source, which is extra work when Steam will handle that for you. Decompiling is also the easiest step in the entire modding process, so if it's too much for you then I'd recommend turning back now.

Honestly your entire post sounds like you're looking for a lot more "help" than you'll ever get.  Modding ONI involves mucking about in the internals of the game and you have to accept that and be comfortable with it.

  • Like 2
Link to comment
Share on other sites

On 1/28/2021 at 1:58 PM, AzeTheGreat said:

mucking about

I just finished a few hours mucking with the dev and deploy environments for the ONI mods, and I think I have a handle on where everything is supposed to live. I sort of journaled the steps, so I can likely update the "Modding: How Do I Even" guide :p

The decompiling step took just a few minutes to understand and execute for me - happy to help via DM or on Discord if anyone is trying to get their own modding environment working and running in to problems.

  • Like 1
Link to comment
Share on other sites

A few days ago we updated the guide for the mergedown changes, including descriptions of changes to the metadata files, and updated the mod template. Now with things calming down a bit hopefully we'll be adding more detailed content.

  • Like 2
  • Big Ups 1
Link to comment
Share on other sites

Just wanted to give a shout out to the maintainers of the Modding Guide. I was able to create a (tiny) mod I wanted in a few hours instead of days or weeks. I genuinely appreciate not having to dig around multiple ancient forum posts, Discord channels, arcane config files etc... ugh.

Instead everything I needed to get up and running was there in the guide. I could focus on the mod I wanted to create instead of wasting hours troubleshooting the dev environment and stuff.

Thanks again!

  • Health 2
Link to comment
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now
 Share

×
  • Create New...