Jelly - Yet Another Wibbly Wobbly Modding API [Alpha 8 Build 2283]

Modding Outdated Mods
1

Since there seems to be some interest around regarding Jelly I’ve decided that since I’ve hit a pretty milestone, I might as well go on some sort of experimental public Alpha.

##Things you need to know before using Jelly or any mod that uses Jelly:

  • Jelly is an experimental release of an alpha of a memory of a cyborg warrior trying to find its deadlock inside a JSON.
  • Things will break. I’m saying in the official manifest below that this should not happen - and that’s not the case yet. The Bottle o’ Jelly is the goal, not the current situation. It’s sort of the concept that I am aiming at - we’re not quite there yet.
  • There will be limited support. I’ll do my best to communicate what changes via commit messages mainly (a perfect opportunity to get a bit of GitHub experience:.!) and sometimes for larger updates/when there is demand in this thread. Just like the real game, Jelly is still heavily changing all the time.
    Especially can’t I do anything about third party mods or outdated/old versions of Jelly because there’s no version number yet - I wouldn’t know which version you’re actually using (unless it’s the most recent one from me) - sorry!
  • Limited documentation. I’ll throw up a page or two in the Wiki about things works, but it’s not going to be a crash course into modding. If you want to use Jelly, at least right now, some basic knowledge (what is an alias, manifest, JSON, mixinto, …) will be required.
    However, there is no need for lua knowledge (yet). You can go pretty far by simply copy-pasting stuff others or I have written and change a line or two.
  • There won’t be public snapshots/nightlies. If you want to use Jelly, you’ll have to download the zip archive from GitHub. Mod authors may offer Jelly as smod file that they know is working with their mod.
  • Jelly might require RP. It’s possible that I’ve put a RP function or two in the code somewhere (hi PrintTable!) and that might cause errors if RP is not present.
    Of course, once Jelly has replaced RP completely, this won’t be a requirement anymore
  • Bug reports are very welcome - but please, I need more information than “X does not work”. To allow me to deal with the problem quickly, I’ll need more information - basically, I just need your stonehearth.log. If you have any error in the console, the log file is worth much more than a screenshot. If something doesn’t work, check the log file for any thing that sounds like programming gibberish or “error”, “exception”, that kind of stuff. If there is, upload it to pastebin/GitHub gists/dropbox/something like that.

This sounds all very restrictive and frightening, but I don’t want to get anyone’s hopes up. There’s some pretty neat stuff you can (or will be able to) do with Jelly, but you have to be prepared that you might need to invest some work to update it to a new revision of Jelly/Stonehearth right now.

Without further interruption, the “official manifest” which would be about what I’m aiming at - most of this isn’t complete yet, but pretty well thought out.

Bottle o’ Jelly

Jelly is an experimental framework built on top, with, over and sometimes under the official Stonehearth modding API. Its spiritual predecessor was RP, whose code is the base for Jelly.

So Jelly is RP 2, right?

Nope, it’s not. While - at some point - it is going to provide about the same functionality as RP does, Jelly goes a completely different direction. RP relied heavily on users listening to events and patching things - Jelly is more data driven. It is less the director of mods and more of an actor - instead of ordering around all the mods, it’s merely organizing them.

However, Jelly and RP can co-exist - as long as RP still exists.

What can Jelly do?

Jelly itself does nothing. It is merely a library that can be used by mod authors to make their life easier or to coordinate multiple mods accessing the same resources. It has multiple parts to achieve that.

jelly.mod

jelly.mod is a class that can be inherited from in your own mods. It’s a scaffolding tool, that means that mod authors can inherit from it to quickly build simple mods - including configuration, dependencies and sometimes simply convenience.

Extended libraries

Jelly adds new libraries that make your life easier. jelly.timers contains several functions dedicated to timing, whereas jelly.util provides several functions for convenience. jelly.resources deals with some nastier resources and jelly.linq is an experimental library to bring .NET’s LINQ functionality to lua.

New data sources

lua is a powerful tool - and a complicated one. Stonehearth aims to separate script (“controller”) and data (“models”) by storing data in JSON files. That support is still incomplete - that’s where Jelly comes in handy.

Jelly overrides functions and complete classes to add model functionality. An example would be the world generation, where jelly:index:trees controls which trees are spawned - how and a bit about the where too.

New events

For those who wish to wield a mightier sword, Jelly adds new events into the existing code. This includes both simple information events about things happening as well as queries - where multiple mods can either change directly or propose changes.

Somewhat documented.

Jelly’s API is documented - in the code. Preparations to have something create Wiki pages for that are already in progress.

Terms and Conditions: The Royal Jelly

Jelly is a community made, inofficial project. There are several things you should keep in mind while using Jelly.

Jelly is a parachute, not a safety net.

  • It’s possible that Jelly breaks with every game update. It’s possible that I release versions that are absolutely unusable. It might take a few hours up to a few days to get a new (and working) version running.
  • Things can break. Things will break. Jelly is just as much of an Alpha construct as the game itself. While the goal will be to minimize damage, it cannot be guaranteed. Prepare to have your mod rustled.

Jelly is alive.

  • Jelly will adapt. Depending on current needs and recent changes in the official API, Jelly will change. Most of the time, the backwards compatibility can be kept - but it’s no guarantee.
  • Changes will be communicated. If an update, be it Stonehearth or Jelly, breaks something, you will be informed about it. This might not happen in advance and as usual takes some time but the idea is that you get changelogs that include workarounds or fixes for current code.
  • Jelly isn’t built to last. Jelly will disappear. The further the official API progresses, the smaller Jelly will become. If a Jelly feature is implemented in the official API, Jelly will first redirect to that feature and deprecate itself. After some time, that feature will be removed from Jelly completely.

Jelly is autonomous.

  • Jelly deals with overrides. Jelly deals with monkey patching, hacking, hotfixing and all that stuff. Ideally you don’t need to do any of these things in your mod to get running. This allows you to worry less about updates - and more about your mod.
  • It’s doing a lot of magic that you as player or mod author may not be aware of. It may change how the game itself (internally) behaves - which can break mods that are not aware of such changes and are not using Jelly themselves. This is likely not going to be a problem, but it could be one.

Now to the interesting part:

What can Jelly do (right now)?

  • A (quite heavily) rewritten Landscaper allows mod authors to change the spawn behaviour of trees, bushes and flowers. You can add your own tree by mixinto into the JSON Jelly provides. An example would be @Alfie’s More Trees Mod. A rough documentation can be found in the wiki.
  • The new game handler has been hijacked too and allows modifying what is spawned at the very beginning (i.e. the camp). Documentation.
  • A few utility functions to make stuff easier - not necessarily faster, but definitely easier.
  • All of the Jelly library functions (i.e. inside jelly.) are documented. Although I’ve yet to write a program that creates a readable documentation out of it, I think it should be somewhat understandable what a function does.

So that’s it, more or less. As always when I release something of this scale, I bet there’s going to be an update within two hours that does the same or changes enough code to give me a headache for an hour or two. Good thing it’s Sunday this time! :grin:

A rough timetable of things that are on my todo list with this would be:

  • A bit more modification of the Landscaper. There’s stuff with boulders that can be done and custom generators would be nice - for people that want something like bushes, but not exactly
  • Fixes to the landscaper. The place_item functions I’m using have some nasty side effects that might be hidden - for example, cluster is simply ignored in the mountains.
  • Once that is done, I’ll get on jelly.mod to provide a base for mods. The general idea is to have something that has a few callbacks, namely extends (“config was available and has been loaded”) and load (“Jelly approves of your mod - please load your stuff now”). Naming subject to change.
  • Copy the whole mod loading thing from RP to Jelly, but different: Register with Jelly and wait for the callback from Jelly that your mod may load now. That way we’re avoiding nasty popen things.
10 Likes
2

I read nearly the entire post, and now… I’m hungry…

this is some awesome stuff!! keep on producing @RepeatPan… sometimes I truly think you are a machine… a lovely Swiss machine of chocolatey goodness… :chocolate_bar:

3

Yes, this is really awesome stuff… without it my mod wouldn’t be alive!

4

Right, so just as a heads up, Jelly was completely compatible with r48/r49 - minus a very small change in the landscape generator which merely changes the density map of trees a little bit.

jelly.timers has been added as well and seems to do quite okay as far as I can tell, it was a straight port from RP after all.

jelly.mod, the next part, proves to be more difficult than anticipated. unclasslib is not as smart as I would like it to; it’s actually really stupid. So I’ll have to see how I can… make it smarter, I guess.

5

Stupid in what ways? Is there another lua class library that you would recommend?

6

I was expecting it to have some support for virtual functions but that isn’t the case. My first idea was to have some sort of “mod base” class that would provide generic callbacks (on_loaded, on_config_loaded, on_entity_created if defined) and clients simply inherit from that base, define functions they need and call it a day.

Because unclasslib is putting the whole context into the old class however, that’s not possible. It’s virtually impossible for the parent class to access any child data (unless you have passed that at some point, i.e. ParentClass:register(self)).

Even then, I find it somewhat weird that the documentation and the library itself are so out of sync - unless I’m mistaken. One example would be named classes, but class('ClassName') is throwing an error (with class not supporting this behaviour at all from what I can tell) and my_class.__name does not seem to do anything at all. I haven’t read the code myself, but I’m somewhat sure that the doc’s way of calling self.classname isn’t working.

I’m not aware of any - I haven’t really used classes in lua at all so far, with the exception of some smaller things with __index and __newindex. I guess unclasslib is okay if you plan on having just a wrapper for those - but for anything else, especially inheritance, it seems useless.

I’m not sure if I could even come up with a better class implementation, or what I would expect from one in detail. Having dipped in C# area for a bit too long, I’m afraid I would get fancy ideas with abusing __index and __newindex to also allow (virtual) setter/getter properties…

7

I’ve tried my luck at implementing a very, very basic class functionality. I’m not sure how pretty it is because it’s actually indexing everything (which could be avoided by (deep?) copying all members from the class into the object - but that’s a waste of memory then) but for my mod class it should suffice.

I can’t see the use of multi-inheritance either, so I’ve stuck to simple inheritance. My class never switches context, it operates always on the object itself - which means that self.some_property is always first queried in the object (if defined), then the class’ definition, then the class’ parent’s definition, and then recursively up the ancestry, no matter in which class the function was called. This could have speed disadvantages, but then again I’m sure that unclasslib isn’t exactly working fast either.

It could be improved (a lot), for example by creating a table with parents instead of recursively calling __index - but for my scenario (simple inheritance with overriding/virtual functions) it seems to work so far. I’ll use it in jelly.mod and see what happens.

Code with test case so far: Lua code - 102 lines - codepad

8

Update.

As a side note, Jelly still works, so this is purely for those who wish to have some new toys to play with.

Changes:

  • Added jelly:index:camp_start. Documentation of the JSON here, the JSON currently here. This is overloading the way the start camp is spawned, i.e. the first villagers, fire pit, entities, banner… It allows complete overriding and of course, modifying those things. This could be of interest to @Avairian and @Miturion I suppose. For now, I simply copied the original functionality 1:1, but if there’s more… “detailed” things requested (such as specifying name/gender/what not for citizens), I’m sure that can be arranged.
  • jelly.timers is now available. I pretty much ported over the RP timers and added one or two things, namely jelly.timers.now() and the ability to have timers on the client, too. I believe the client has even more precise timers than the server, I’ll have to see if I’m going to introduce such high-res timers to the server too.
  • Added config functions. Nothing too fancy to be honest, it’s one of the things I’m actually thinking about dropping altogether - but we’ll see.

As usual, no official release (until I’ve get The Kitchen running), just a notice that it has been updated. On the same term, I guess, I should mention that RP and some of RP’s mods have received smaller updates too, namely rp_developers_dreams has no fog of war issues anymore and rp_console speaks client commands too.

Edit: It seems that I’ve accidentally linked the wrong documentation - this one’s correct.

3 Likes
9

I-think-it-should-work update for Alpha 3 now on GitHub.

Right, so Alpha 3 hit and, as expected, lots of stuff broke. Currently, my game is not starting, even after removing RP. The game logs are all, as far as I can tell, empty, so I’ll need to investigate what could go wrong one mod at a time.

In the meantime, I’ve committed the first bunch of changes. They’re the ones that immediately lit up (and the only ones I can see as of now) and are basically just a bunch of renamings. This is likely not a working build and I haven’t investigated the whole changes yet. I’m somewhat busy on finishing another project of mine in GMod, so my Stonehearth time is very limited.

Edit: Yupp, one of my… 21? mods seems to mess up. I’ll do a few tests just with Jelly, which seems to suffer some new bugs. I’ll keep this post up-to-date.

Edit 2: new_game_call_handler should be working as expected now. I’ll have a look at the landscaper now.

Edit 3: Well, that was rather painless. I would say that Jelly is completely updated to Alpha 3, but as always, no warranty. Report any bugs you might encounter and I’ll have a look. I did a quick test with @Alfie’s spooky trees and it… kind of seemed to work?

Remind me to update rp_silence at some point…

10

@RepeatPan is there any future plans of updating Jelly? I just saw it and it looks great, but I guess you might say its a little outdated.

11

I had very high hopes and expectations for Jelly, but people didn’t seem to like the concept or the idea at all - so it was scraped, like all of my Stonehearth projects.

I’m willing to invest a lot of my personal free time into such things, but if there is no demand for them, I don’t see a reason to continue them.

The last release seems to have been around Alpha 3. I expect most things still work or require very little adaptation, but I have been out of the loop for quite some time and Stonehearth doesn’t even start any more on my computer. You could say that I have, for all intents and purposes, lost interest in the game.

2 Likes
12

Never mind the modding stuff a minute - WHAT?! :open_mouth:

Seriously, this is important at this stage in the game - should file a report so @sdee or @not_owen_wilson etc can have a look.

1 Like
13

It’s much more of an issue with Steam than Stonehearth I believe. It’s stuck in an endless “Download” mode with every attempt defying installation successfully by throwing some error at my head that made me think my hard disk was bad.

But nevermind, I’ve just tried launching it again and it still works - inclusive rp_console. I’m flattered. So whatever Steam borked back then seems to have fixed itself.

Still, there’s no demand for any project, with ShPad probably being the biggest setback.

2 Likes
14

@RepeatPan That’s to bad man. Thanks for what you’ve done. Is Jelly on GitHub? I’d love to take a look.

EDIT: Found it.

15

Guess who’s back. Jelly has been updated to Alpha 6, Build 166. You can find the latest release on GitHub. Because there are a few more modders and interested here, let me explain a few things:

  • Jelly is merely “wrapping things” around in a different way. Currently, it offers ways of modifying the landscaper (responsible for tree and bush placement) as well as the new game handler (including the ability to set which items should spawn at the beginning, where and how many workers there are, what professions they have - and more). By just installing Jelly, you actually won’t see anything different.
  • Jelly is incompatible with mods which attempt to modify the landscaper too (there are a few around). In all likeliness, Jelly will just overwrite whatever changes other modders have made.
  • It’s not hard to maintain Jelly and even less difficult to adapt maintain stuff made with/for Jelly. For example, adding ancient trees required me to create a new template as well as adding ten lines to an existing JSON. Most of the functionality was already in Jelly to support these changes.
  • As “consumer” of Jelly (that is, mod author using Jelly), you only really have to worry about JSON changes (at the moment). All the nasty lua implementation is done and maintained by me.
  • Feel free to request features, report bugs or ask questions.

But now, on to a very serious and necessary topic: jelly_silence.

9 Likes
16

Thanks. Please keep up the work.

1 Like
17

welcome back :stuck_out_tongue_winking_eye:
Good to have Jelly among us again.

2 Likes
18

I thought not much had changed but @Drotten was right - there was a little change in the NewGameCallHandler. Because I’m using jelly_quickstart, I need to use that function and therefore, everything worked fine.

Jelly updated, now requiring Alpha 7 Build 183.

3 Likes
19

Jelly mod won’t load… I downloaded that ‘jelly-master zip file’ on the page. Is that correct? (When I throw Jelly in the mods folder, Stonehearth won’t load… I click it, the blue wheel of loading goes around and then dies out, no Stonehearth window)

20

Did you unzip it into a folder called jelly? Can you post your stonehearth.log?