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.
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.
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!
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,
clusteris simply ignored in the mountains.
- Once that is done, I’ll get on
jelly.modto 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