Please note that Name Lists does not itself include any custom names.
Namelists allows other mods to register custom lists of names for entities that support backer names (such as train stations or science labs). When an entity is built, if there is a valid name list registered for that entity, Namelists will request a name and assign it to the entity. Lists are searched for first by entity name, and then by entity type, and finally from any general-purpose lists. If no custom lists are found, a random Factorio backer name will be applied.
There is also a hotkey (Control +N by default) which will choose a new name for the selected entity.
The mod settings allow you to use custom lists with the original backer names if you so desire, instead of simply replacing them outright.
For example, if there are custom lists available for both the type locomotive
and the name nuclear-locomotive
, when a player builds a nuclear locomotive it will use a list specific to the name nuclear-locomotive
Renamer will use these lists to select a new name from a list when its randomise button is clicked.
To add your own list of names, a mod must request the custom event handler in on_load
, and when that event is triggered use the remote interface Namelists
and call register
to register itself with Name Lists. If the mod has options that add or remove available lists, it should call the rebuild
function from the Namelists
interface when those options are changed.
For examples of the above functionality, see Japanese Station Names and Nuclear Locomotives.
Note that names do not have to be randomly-selected, they could be generated based on properties of the entity being renamed. Japanese Station Names includes an (inactive) example of this, showing how station names could have their direction added as a prefix.
How to register your own list
In your mod's control.lua
script, add the following to call Name Lists' get_events
interface to get the ID for the custom rebuild event, and add a handler for that event to register your list:
local namelist = nil
script.on_load(function()
namelist = remote.call("Namelists", "get_events")
script.on_event(namelist.on_list_rebuild, function(event)
remote.call("Namelists", "register",
{interface = "MyInterface", func = "my_remote_function_name", category = "type", target = "lab", weight = #names_table})
end)
end)
interface
is the name of the remote interface your mod provides
func
is the name of the function you wish to use for this type/name/generic list
category
is optional, currently supported values are "type"
and "name"
target
is the entity type or name this list is for, this must also be specified if category
is set
weight
is a weighting used to help choose when multiple lists exist for the same type/name. This must be specified, and the suggested value is the length of the list names are being selected from.
The reason why weight
should be the size of your list of names is that so if multiple lists with different sizes are registered for the same category, each name on each list will have an equal chance of being selected
Define your list's remote interface:
remote.add_interface("MyInterface", {my_remote_function_name = my_local_function_name})
.
Define your function to choose and return a name:
function my_local_function_name(entity)
return names_table[math.random(#names_table)]
end
Your mod does not have to simply pick randomly from a list. When your function is remotely called by Name Lists, it will be given a reference to the entity this name is for. You could use that to generate a name at run-time based on (for example), the direction a train-stop is facing, or the name of the player who built it.
There is a commented-out example of such a function in Japanese Station Names.
If your mod has settings that alter which lists are active or make other changes that need to be updated in Name Lists, add a handler to defines.events.on_runtime_mod_setting_changed
that invokes remote.call("Namelists", "rebuild")
if your mod's settings have changed.
Known Issues
Train stations do not get a random name assigned if they are hand-built without a ghost present. This is to prevent random names replacing blueprinted station names, as there is not currently a reliable way to detect the absence of a ghost.
Workarounds are to either build stations with bots, or use Shift+click to place a ghost first and then manually build over that ghost.