API documentation?

Is there any chance that we can get some sort of basic API for how to interact with objects in the Lua Console (or does one already exist and I’m an idiots? …because I’m often an idiot, so…)

There isn’t a proper reference, at least right now. However, pretty much anything you see in game or mod code can be run in it.

Is it possible for me to modify entity attributes via the Lua Console? In particular, I wanted to change the hair color of one of my characters…

My biggest problem is I’m not sure what all the methods are in there. I’m not sure if it’s that I don’t understand Lua, or that I simply am not aware of the names of the methods. Any guidance would be appreciated (and thanks for the swift response!)

There’s a mod that allows customization of any hearthling after you’ve started the game: Steam Workshop :: Hearthlings of Many Faces

Changing hair color and the like is probably handled by the customization component, which reads the available customizations from json files. There’s also a customization service which makes use of this for the roster screen.

1 Like

Thanks for the quick response :). I was kind of hoping to use this as an intro to figuring out the Lua Console though… Kind of the “teach a man to fish” theory, ya know? (Though if push comes to shove, I’ll look into the mod.)

Personally, I think I’ve reverse-engineered most of Stonehearth’s code using the console (my own one before the official one was a thing; then the debugtools one, and these days the official one). I’ve liked that approach; it gave you very fast feedback on what you do. So I get an idea of where you’re coming from.

Keep in mind that the console has severe limitations though. Entities get serialized as strings, so you’re not ending up with a lot of useful information. Additionally, because it is synchronized, some data structures don’t work well (especially those involving loops and references).

Not sure if it’s still the case, but a while ago you could actually crash the server process (not the game per se) just by trying to get it to serialize a nasty object. I think it’s still possible to severely freeze the game for a few seconds at least.

As for the documentation, “e” contains the object you’ve currently selected. I recommend you save it somewhere else, so click on something, do some_ent = e, and move on. That way, if you accidentally click something else, you won’t lose the reference. Other than that, like the others said - it’s basically just a REPL, so you can do whatever you would do in a normal game.

1 Like

Ah, it’s sound like what I need to do then is learn a bit more about lua… It’s been on “the list” for a while now, sounds like it just bumped itself to the top.

Anyway, I’m also not sure about my methodology just, you know, from the outset. Basically I just open up the object browser, then try to use the lua console to pull out entities from whatever my current selection is… I had very limited success.

Do you have any notes on what you’ve figured out? I’m just trying to get a foothold, I feel like if I could do that, I could probably start making headway on my own.

There’s a couple super basic examples here near the end of the page, in the Lua console section:

Not sure if they’ll help you :confused:

Certainly knowing the available functions helps (which means looking into the game’s files). What RepeatPan says is true, sometimes printing large objects / nested objects might hang or crash the server.

which means looking into the game’s files

I’d do this in a heartbeat, how do I get ahold of it though? I wasn’t figuring you folks had the source code just lying around? Or do you mean the JSON data files?

The Lua files themselves, inside the stonehearth.smod (go to your “mods” folder inside the Stonehearth folder, rename any .smod to .zip, and uncompress it. The link I pasted has more explanations on it in the first sections).

We don’t really have any documentation on the C++ components, though. But you can see what services, components, etc there are by peeking into the Lua files.

Thanks! Lol, I’m always wanting to read the code, glad to know that’s a bit of an option here. This should really help :slight_smile: