Pronounced "
skins factored
", written as "!skins
" in all lowercase
This is a Factorio library mod that makes it easy for other mods to add custom characters (skins), with a character picker.
This mod takes a different approach than other skin-changer mods: instead of trying to extract the skins from multiple installed skin mods, it acts as a library for mods to include, meaning a player can install just one skin mod, or any number of them, and they'll all work as expected (if they use this library).
This library was written to be compatible with almost all mods that edit the default character prototype. It is explicitly compatible with Jetpack, Space Exploration, and RPG System. If you encounter any issues with compatibility with another mod, please make an issue!
This information is only for developers wanting to use this library! See the mod portal for information for players.
Adding support for this mod is simple, and can be done without losing support for other character-selecting mods.
You can add multiple skins in one mod if you wish, just follow the steps for each skin you want to add, making sure to use a unique skin id for each.
Before calling the functions in either phase, you should first check that skins_factored.schema_version == 2
(the current version).
First, add the following line to your settings.lua
:
skins_factored.register_skin_id("your-skin-id-here")
Skin IDs must be a valid prototype name. This is what players will see when using the /character
command. Localization files are used for all other skin changing interfaces.
Then, add the following lines to your data.lua
:
skins_factored.create_skin("your-skin-id-here", {
icon = "path/to/image.png", -- shown on the inventory button and in the gui, REQUIRED
reflection = "path/to/image.png", -- reflection for water, OPTIONAL, will default to the default player's texture
armor_animations = {}, -- table of CharacterArmorAnimation, REQUIRED
-- see below for what this should look like
corpse_animations = {} -- table of AnimationVariations, OPTIONAL
-- if not present the default character corpse entity is used (no custom corpse is generated)
})
The animations
key is identical to what you would overwrite the default character.animations
table with. The corpse_animations
key is identical to what you would overwrite the default character-corpse.pictures
table with.
The number of animations and what armors they apply to must match between animations
and corpse_animations
. The animations[n].armors
table is used to merge armor tiers in case your mod does not have all 3 armor tiers (or more if other mods add more tiers).
For an example of what the animations
key should look like, see here.
Factorio wiki documentation for types:
Create a localization file with the following contents:
[entity-name]
character-SKIN_ID=Name for the skins in-game character, shown in the skin selector GUI
character-SKIN_ID-corpse=Name for the skins in-game corpse
[entity-description]
character-SKIN_ID=Description for the skins in-game character, shown in the skin selector GUI
character-SKIN_ID-corpse=Description for the skins in-game corpse
[string-mod-setting]
skins-factored-selected-skin-SKIN_ID=Name for the skins setting dropdown item (required, but should be the same as the entity-name)
[string-mod-setting-description]
skins-factored-selected-skin-SKIN_ID=Description for the skins setting dropdown item (required, but should be the same as the entity-description)
Make sure to replace the word SKIN_ID
in the key with the same skin ID you passed to skins_factored.register_skin_id()
.
Finally, add the following to your mod's info.json
:
"dependencies": [
"skins-factored >= 1.0.0"
],
If you are creating a new skin mod and are using this library, you must use a hard dependency (the JSON above does that); do not try to overwrite the default character
if this mod isn't found!! That will simply create the plentiful bundle of issues that this library was written to avoid.
If you're migrating an existing mod I highly recommend you also make this a hard dependency and remove any code that generates the prototype yourself or interacts with other skin changing mods. !skins is designed to make this no longer necessary, improving compatibility with other mods that edit the base character, and providing automatic compatibility with miniMAXIme and RitnCharacters.
If you are porting an existing mod to work with !skins, you must create a .json migration to convert the old character prototype name to the new one generated by !skins.
{
"entity":
[
["your_old_prototype_name", "character-SKIN_ID"]
]
}
your_old_prototype_name
is the name of the old prototype your mod generated, and SKIN_ID
is replaced with the skin's id that you passed to skins_factored.register_skin_id()
.
For more information, see the Factorio Lua API documentation for Migrations.
One exception is that this is not needed if your mod just overwrote the default engineer's sprites and didn't add any prototypes.
Copyright (C) 2023 Penguin_Spy
Licensed under GNU General Public License v3.0 or later. See LICENSE
for the full text.