JContainers by silvericed
Skyrim » Modders Resources and Tutorials
Added: 10/01/2014 - 10:23PM
Updated: 07/04/2016 - 11:50PM

25,917 Endorsements

3.2.6 Latest version

256,435 Unique D/Ls

512,710 Total D/Ls

1,049,412 Total Views

Uploaded by silvericed


Last updated at 23:50, 7 Apr 2016 Uploaded at 22:23, 10 Jan 2014

I have started implementing domains feature*. Description draft:

Any mod author may have one or few JContainers domains, containing _only_ the author's data. Which in return allows us to remove domain-specific data completely when a mod gets uninstalled. It's important, as it allows to remove the objects you forgot to release, i.e. absolutely everything.
Every domain is virtual, self-sufficient copy of JContainers. You can't transport your data across domains (unless use writeToFile/readFromFile).

Basically, every user-created domain is a copy of compiled JContainers_DomainsExample.psc file and just a folder inside /JCData/Domains/


DL link to try domains feature -
Example of the mod that use domains (or domain?) -


The main goal of the project is to extend Papyrus with JSON-based data structures (arrays and maps).

Why bother?

If you are familiar with other programming languages, sooner or later you'll notice the lack of many, many must-have features in Papyrus. First of all, the only data structure in Papyrus is Array. The problems:

- No way to append, erase values from arrays, put an array into another array (no nesting), put Form, String or Float value into the same array
- The Quest are global. And being used as data holders. And Records are imitated via arrays of forms, floats etc. You allocate your 128-element-sized arrays, fill them with numbers, and when there isn't enough place you say "Boom!". Yeah, also there is `int index` field which reflects fullness of your arrays
- Configs? No, we haven't heard of that. All you have is your hands to hardcode your data directly into scripts, say hundred or so lines, FormLists and GlobalVariables
- Want to pass lot of data to another function? 10-20-parameters is the only way to go

And I didn't mentioned the lack of associative containers or impossibility to load or save a data into a file. Though, Papyrus is a specialized language, we shouldn't expect much.

The solution

There is no easy way to extend existing Array (which would require to change Papyrus VM, which is tricky since we have no source code) or add new data structures into VM, thus JContainers implements it's own data structures, garbage collector and other infernal internal stuff from scratch. Features, offered by JContainers:

- Data structures (arrays, dictionaries). The basic building blocks, with use of whom, you can do lot of things, combine them in any way. E.g. use JMap to imitate Fallout 4 structures (JMap is still better as you can add/remove any field dynamically AND FO4 isn't Skyrim)
- Form observing - observe form delete events. Explaination here.
- Ability to import and export any complex data structures to and from JSON files preserving connections between them
- Embedded Lua - to get rid of some part of clumsy Papyrus code and move it into Lua. Lua scripts are being compiled into fast machine assembly
- C++ API - to create your own SKSE plugin and be able to interact with JContainers, maybe extend it. See "developer resources" archive in Files section for usage example.


Quick feature overview
Latest documentation
Watch project news and updates on GitHub

Special thanks

- to Saerileth and Gooser, without your interest that project would be abandoned on very early stages
- to Skwerlman and Alexdunn for documentation improvements
- to Verteiron for feedback, bugreports
- to RealAntithesis for feedback, object' identifier generation idea
- to Djarb, specifically for default-return-values idea


SKSE team - it would be impossible to imagine Skyrim modding without it
boost framework authors - real treasure for any C++ programmer
Akheron, who made jansson - nice JSON parsing library
Lua and LuaJIT creators

Mods that use JContainers (the ones, I was informed about)

Feel free to add more mods here

Nexus mods

Skybox - transfer items across diff. characters
Pose Picker - Idle Poser
Metachest - A Сross-Savegame Chest
VioLens - A Killmove Mod
Stat Control Panel
HT Casting Regeneration
Swift Potion Reborn
AH Hotkeys
Key Input Framework
Proper Potion Names
Hook Immerse
Familiar Faces
Druids Den - Collectors Edition

Loverslab mods (there should be some adult content warning):

Radiantprostitution Tweaked
Creature Framework


- You are free to shoot into your own foot bundle JContainers. But it's not advisable to do it, as this will inflict your users, as the plugin gets updated quite often and JContainers version downgrade, version conflicts due to mods bundling different versions WILL cause issues¹. This is time-proven fact.
- It's up to you to report to a user of incompatibility of installed JC API version and the version mod has been compiled for the best user's experience. Valid condition is `JC.APIVersion == hardcodedAPIVersion && JC.featureVersion >= hardcodedFeatureVersion`.
- The files in this plugin are not to be modified under any circumstance as that could cause problems when a load order includes multiple mods that use the plugin and one or more mods have modified the files in this plugin.

¹ Know 'symptoms' are:
- JC donwgrade may causes data loss
- users start play 'load-order' game, putting JContainers above/below some mods