[MOD] Hearthlings of Many Faces

With this mod you’re able to customize the looks and names of your citizens.
Here you can create an amazon village, make everyone be part of a huge family, create a village full of clones, name the shepherd after yourself, or whatever you feel like!

What it does

Whenever you recieve a new citizen to your kingdom, a new window will show up; where you can edit the citizen’s name, gender, and models. Here’s an example image and a breakdown on every detail (though the image is a bit outdated now, the description still holds).

Extra settings

There are some extra options found in user_settings.json:

  • Customize embarking: enter customization for the citizens that are embarking.
  • Customize immigrating: enter customization for the citizens that are immigrating.
  • Zoom to entity: Zoom in on the hearthling being customized.
  • Pause during customization: Pause the game while customizing.

All of these can be set to either true or false.


A new console command is available (open up the console by hitting Ctrl+C):

  • homf_custom - Whilst having a hearthling selected, this will start up the customization process once again for that hearthling.


For those that are looking to add localization for this mod:

The title and tooltip strings are located within the mod itself. However, the strings for the category types and for the names of the model / color are accessed through Stonehearth’s en.json file, all of which is grabbed from ui.shell.select_roster.

Furthermore, in general the keys for the strings are all in lower case and with the spaces (’ ‘) replaced with underscores (’_’). E.g., “Male Hair 2” has the key value “male_hair_2”, so its location within en.json is ui.shell.select_roster.male_hair_2. But, for most entries that were missing from Stonehearth’s en.json file, they were added to this mod’s own locales/en_fix.json. Take a look inside this file for an overview of the strings that are translatable. Keep in mind though that it doesn’t include possible entries from other mods that add their own models and colors to the hearthlings.

Known issues

  • There is a risk of your hearthlings getting baldspots, a workaround is to switch between the genders until the baldspots are gone. This is most likely a problem on the engine side, which can’t be fixed from this mod unfortunately.

  • The eyebrows for males are offset whenever the hearthling is generated as a female and subsequently changed to male (if the hearthling is generated as a male to begin with, this bug doesn’t occur). This is a bug on the engine side, and nothing I can do. However, the developers have been notified of this but their priorities lies elsewhere than to fix what is causing this issue, so we need some patience before this is fixed…

Future implementations

  • The camera orbits around the citizen being customized.
  • The camera follows the citizen during customization.
  • Can enter customization for a citizen later on, maybe through some kind of potion.
  • Access to the configurations through the settings menu.
  • Ability to customize a hearthling from the embark screen.

Download links

Homf (Dropbox)
Homf (Google Drive)
GitHub repository

Also available on Steam Workshop.

Have fun!


Your wish is my command. I didn’t catch that little update - the new version should work fine with latest again. Although, I must admit, I’m not sure where you’re using Jelly at all after browsing quickly through the code :wink:

In general, if it’s only the Jelly.Console+ commands you need, you can make it optional by using something like this.. This will make Jelly.Console+ an addition - if you don’t have it, nothing will break.

A few notes from my side:

  • Don’t register your mod globally (custom_citizens_mod = class()). I haven’t downloaded/tested this, but with strict lua in place, this should throw an error. In SH, each mod is supposed to return an object in its server_init/client_init script representing that mod. For example, jelly is always only defined local within jelly, but because I’m returning this reference in the last line of jelly_server_init.lua, Stonehearth fills _G.jelly with that. It’s the recommended way to do it. I wouldn’t touch global stuff unless you’re sure you want to.
  • I’m not 100% sure if this has changed and is still relevant, but last thing I’ve heard was that radiant.events.listen(something, something, function() end) was not allowed - or rather, its having unexpected outcome (I can’t remember the details, it was something along the lines of "there is no self, so the function isn’t stored anywhere and because it’s a weak table the function gets GCed). Instead, use an approach where your mod is an object (see Jelly/Jelly.Console for an example). You’re definitely avoiding any GC problem that might arise and as far as I know, you’re fitting into the general idea what a mod should be structured like.
  • radiant:entity:post_create with stonehearth:camp_standard might not be unique enough - for example, jelly offers you to change that banner, in which case your mod would not be loaded. In case you wish to stick to jelly, I’ve added jelly:camp_created which you can listen to on jelly (radiant.events.listen(jelly, 'jelly:camp_created', function(banner_entity) end). This event is called asynchronously as soon as the whole camp has been created. There’s no official event yet. If you want to get one after the camp’s name has been set, that can be arranged too. I suppose this could also offer you the “fool proof way” to figure out who’s embarking and who’s immigrating, as after this event, all citizens should have been created (no idea if whatever table you’re pulling the data from has been updated, however).
  • I wouldn’t use _host:get_config. radiant.util.get_config is more official, although slightly overheaded. In general, relying on the config being existent is pretty dangerous, which is an advantage of util.get_config as it lets you specify a default. Because the JSON is likely cached anyway, it doesn’t make a lot of sense to query the configuration with every update. I would simply save the config in local variables upon initialization and re-use them instead of doing that in _update.

Side notes:

  • I’m actually amazed that saved variables work on mods - but seeing as they are treated as game objects (according to @eval return jelly returning game://object/12). That’s definitely nice to know, I haven’t worked with save data yet.
  • I was about to recommend jelly’s timers over radiant’s timer implementation because I hadn’t seen TimeTracker before. Reminds me an awful lot of jelly’s timer system, although jelly’s is still mightier (in terms of repetition count). I’ll see to what extent I can leverage that.

Just a few things I’ve come across while browsing your code.

I’d recommend the Puzzle Pirates way: Using potions for everything. Missing a leg? There’s a potion for that. Wnat red hair? There’s a potion for that! Would especially work nicely with the color thing they’ve announced a while ago.


I was pretty much only utilizing jelly.PostRootViewInit in client_init.js, since I couldn’t find any other way to initialize my CustomizeCitizenView app. In the future I wish to make Custom Citizen independent of Jelly, but for now it offers convenient solutions for my problems. Also, now you’ve given me more reason to require Jelly. :stuck_out_tongue:

Oddly enough it didn’t give me any error, I did however change so it’s returning an object now.

I wasn’t aware of this. But I’ve changed the code to avoid this kind of listen!

Thanks, works like a charm! :+1:

I don’t know why I didn’t have it in the first place. I guess I started using _host:get_config, noticed it was working fine and then forgot about radiant.util.get_config. I’ve updated the mod with this now though.

Thanks for these awesome notes, they gave me a greater insight in how mods work in SH. :+1:

Ooh, I like that. I’ll see if I can have someone craft this (it’d be great if there was an alchemist or some similar job). Otherwise I’ll just have it as loot from dungeons/tradable item.


So I figured that I’d fix all these bugs that came with the mod, to make the experience less painful than what it was at first. :smile:

Here’s what I did for the new version:

  • Bug fix - Camera no longer jumps back and forth when finishing up customization too quickly.
  • Bug fix - Customization window no longer flashes when loading up a game.
  • Bug fix - Camera is working as normal now (no need to open up the Manage Citizen window).
  • Bug fix - Saving/Loading during customiziation is working perfectly now, so you can safely save when customizing if you’d want to.
  • Bug fix - temporary Zooming in on citizens no longer crashes the game. Though it doesn’t behave like I want it to, in that the camera doesn’t rotate to face the citizen. Hopefully, later on, I can figure out a way to bring this back without having the crashes.

You might have to start up a new world for most of these changes to take effect (not 100% on this, just what I think), that is if you started a world with this mod and then updated it to this version.


wow, I don’t think I fully grasped what you had going on with this mod… well done @Drotten!

did your OP always contain the helper image? I don’t recall that the first time around…


Thanks @SteveAdamo! It’s not too surprising since I did a terrible job at conveying how this mod worked at first. :stuck_out_tongue:

You recall correctly; it was something that was added later on when I realized I needed some sort of explanation. Hopefully this should be more clear about what this mod does. :blush:


Not working with me, I extract jelly from Jelly-Master & throw in your .smod folder yet it doesn’t work… It runs as normal but the mod just doesn’t spring into existance…

wow, this looks promising. :+1:


I don’t know why it doesn’t work for you, I downloaded the latest Jelly and it worked perfectly for me. did you rename it from “jelly-master” to “jelly”? Also you need to make sure to have jelly in your mod folder (alongside this mod).

Also, do you run the stable or the latest build?

Stable. I extracted jelly-master folder from the zip file, compressed it into an .smod zipfile and threw it in the mod folders. With your mod I just threw it alongside jelly and I made sure to rename it to jelly. Somehow it just doesn’t work… Would you mind showing me your mod folder?

@Zhaldak, I’ve updated the mod so it doesn’t require you to use Jelly now, download the new version and see if it works now. :slight_smile:

Sorry @RepeatPan, Jelly’s still awesome though! :wink:

By the way, here’s how my mods folder look like now:

As you can see, I don’t have jelly.smod there and it works fine. Also I’ve tried for both the stable and latest builds and it works fine for both.


Thanks! I’ll give it a try now.

1 Like

It needs to be in a folder called “jelly”, not “jelly-master”. Even if it’s zipped, the folder inside must be named “jelly”. It’s an issue I’m aware of and that I am trying to correct.

i have tried it new citizien appeared but no window? unstable 2193 and new game with mod started? and they doesnt use the mean beds anymore … but this can also come from the normal unstable bugs xD

Is this only when you get new citizens from daily update, or even for your starting citizens? I’ve tried starting in normal mode and peaceful (and even tried with Quick start), but I don’t get this error. I tried with only this mod installed though, you didn’t have any other mods there?

Can anyone else confirm this? If so, can you give repro steps if you constantly get it.

As a side note: my citizens sleep on their mean beds, I don’t know if it’s connected, just wanted to mention it.

downloaded 1.0.4 only mod is my german translation but there is no change in the luac etc just change name informations in the entities? ^^ and with the beds now the sleep in it - was the normal pathfinding issue in this version - also reloaded and waited again a day - no new window at the beginning or at daily update - also no error message

Could you send me your log file? Maybe it contains some clue as to why this happens.

Otherwise you could try to reinstall Stonehearth and redownload Custom Citizens, I kinda doubt it would help but it couldn’t hurt to try. :wink:

here is the LOG ^^


I did a very small change to the mod, you can try it and see if you get it to work now. It was a very minimal change and something that shouldn’t affect anything, but you can always try…

Works perfect now :smiley:

at the moment i try to translate it - but when i change the names from the ui body - koerper etc. it doesnt accept the nextbutton anymore? ^^

edit: issue resolved - just changed windowsize now it accept the buttons and dont give only the sound xD but one question where i can change the name of the bodys? like body1/2 etc? i cant find this as propername ^^