FACTORIO 2.0 WARNING #

The factorio 2.0 version is a very quick patch of the most obvious breakage, there are most likely things that don't work correctly. I only did this as an aid for updating dependent mods, though in the future you may be able to use flib instead, or you may have to wait a while for a proper update, we'll see what happens.

Reporting bugs #

Please report bugs on GitHub.

Why does this exist? #

Because understanding where exactly do recipes take their locale from took me several days of trial and error (and harassing Bilka on discord). I certainly don't wish anyone to go through that again, so I packaged all of the pain into this convenient little library.

For real though, I need to generate virtual signals to represent recipes in Crafting Combinator and for a long time I used a half-assed approach of figuring out the locale that completely ignored ~90% of the mechanism. This (obviously) didn't work for many recipes, so I decided to bite the bullet and do it properly. Since several people seemed interested in my work, I decided to polish it a bit and make it into this lib.

There are also several things that are prone to require updates with changes to the base game. This way only the library needs to be updated, rather than each mod individually.

What can it do? #

The main purpose of the library is to find the correct localised_name and localised_description of prototypes. This of course includes recipes (which are by far the most complicated), but it works for any other prototype too.

It can also give you proper icons for any prototype. This was added because recipes can inherit icons from their products (though differently than locale), but is also useful to parse the various formats an icon can be defined in.

Apart from that, there's a bunch of random utilities that the lib uses itself, but I thought I'd expose them, since they could be useful on their own as well. Notably, there's a prototype type inheritance tree and a couple utilities around that.

How to #

First of all you need to add the lib to your dependencies in info.json - something like:

{
	"name": "moddy-mc-modface",
	"version": "4.2.0",
	...
	"dependencies": [..., "rusty-locale"]
}

should do the trick.

Next, import the modules you want to use with something like:

local rusty_locale = require '__rusty-locale__.locale'

and call functions on them like:

local locale = rusty_locale.of(some_recipe_prototype)

This is for the locale module, for icons you'd replace locale with icons, and so on... You can find the available modules and the functions in them in the reference bellow.

Reference #

locale #

All the functions in this module return a special object that has two properties: name and description, which return the localised name and description, respectively. The properties are resolved lazily, so don't worry if you only need to use one of them.

_of(prototype)_ ##

Get a locale object for the given prototype. The type of the prototype is determined automatically and the proper algorithm is used to resolve the locale. This is the preferred way to use the module as it is future-proof in case some prototype is changed to require a special algorithm.

As this is the "smart" function, it does more work than the specific ones, so it can be slower. This shouldn't be much of a concern, but if you really care about data stage performance for whatever reason and you know the type of the prototype in advance, you can save some time by calling the specific function for that type directly.

_of(name, type)_ ##

Shorthand for locale.of(prototypes.find(name, type)).

_of_recipe(prototype)_ ##

Get a locale object for the given prototype, assuming it's a recipe.

_of_item(prototype)_ ##

Get a locale object for the given prototype, assuming it's an item.

_of_generic(prototype)_ ##

Get a locale object for the given prototype, assuming it doesn't use any of the special formats.

_localised_types_ ##

This is a table mapping the prototype types that support localisation to true for easy lookup.

icons #

All the icons in this module are returned in the icons-only format. This means that it is safe to use the results in a prototype just by setting them to icons.

*Note that the spidertron remote also requires* icon_color_indicator_mask *and* icon_size *to be specified in the root of the prototype. You won't get those from the functions here at all, which shouldn't be an issue in most cases, but make sure to handle them yourself if you do need to (for example if you're creating your own spidertron remote)*

_of(prototype, silent)_ ##

Get the icons for the given prototype. The type of the prototype is determined automatically and the proper algorithm is used to resolve the icons. This is the preferred way to use the module as it is future-proof in case some prototype is changed to require a special algorithm.

If silent is true, nil will be returned when no valid icons definition could be found, instead of throwing an error. This also applies to prototype being nil.

The same disclaimer applies as for locale.of().

_of(name, type, silent)_ ##

Shorthand for icons.of(prototypes.find(name, type), silent).

Note that the silent parameter is not passed through to prototypes.find(), so a non-existent prototype will still throw an error. If that's a problem, use the full form instead: icons.of(prototypes.find(name, type, silent), silent). This way it's clear which errors you want to ignore, but be aware that it doesn't make sense to call this like icons.of(prototypes.find(name, type, true), false), as the potential nil coming from `prototypes.