JContainers by silvericed
Skyrim » Modders resources and tutorials
Added: 10/01/2014 - 10:23PM
Updated: 09/10/2015 - 09:41PM

14,837 Endorsements

3.2.5 Latest version

240,507 Unique D/Ls

313,839 Total D/Ls

625,823 Total Views

Uploaded by silvericed


Last updated at 21:41, 9 Oct 2015 Uploaded at 22:23, 10 Jan 2014

- Google group, JContainers-Users group has been created - a location to ask questions, unite mod developers, post news and what not

I've recently been starting to experiment with your embedded Lua Implementation and I must say
it has been working quite nicely for filtering with predicates it is just so much faster on the containers
and compact then Papyrus. Many thanks, with a bit of creative use I found I could condense a very long
SkyUI config script I was working on to just a hundred or so lines

I used JContainers for my hotkeys mod primarily because:
- It allowed me the flexibility to create my own complex data structures that could be created and destroyed as needed (and written out to file to 'save').
- It allows arrays greater than 128 items, and array sizes that can be determined at run-time rather than the fixed-size papyrus arrays.
- Using JContainers is much faster than using formlists for those things formlists are used for.
I probably wouldn't have finished my mod without JContainers due to banging my head against the wall of papyrus limitations.

It provides features and power that is not available anywhere else. And it is being continually updated
by a developer who has a clear vision of capabilities (e.g. LuaJit) to be included in the future.


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. There is no way to:

- append, erase values from arrays
- put an array into an array (e.g. no nested arrays)
- put multiple value types into a single array

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)
- Import and export data to and from JSON files
- Embedded Lua - it possible to use powerful Lua
- C++ API - interaction with JContainers via C++ interface. See "developer resources" archive for usage example.

Other solutions (biased opinion here)


- Being used (due to low enter barrier? really?)
- No way to create Entry (object with fields via JMap), you have to imitate it by using multiple arrays.
- No nested data structures. Ask them 'how do I create 64x64 grid, each cell containing an entry of type: {"grid name"-string, number, array referencing other entries}?'.
- Human-inreadable, custom JSON format. Ask them 'how do I parse Racemenu JSLOT/JSON files?"
- Is anyone still reading this?


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

Can I help?

Sure! Feel free to do whatever you think is good - post feature requests, report bugs, improve Wiki , improve source code.

Special thanks

to Saerileth and Gooser, without your interest that project would be abandoned
to Skwerlman and Alexdunn for documentation improvements
to Verteiron for feedback, bugreports
to RealAntithesis for ideas, feedback
to Djarb for feedback


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


- You (as mod author) are free to bundle this plugin. Note that this may lead to downgrade issue, when your mod bundles older version, overrides new version (bundled by another mod or installed manually), which may lead to JC data loss, JC-dependent mods may stop work. I warned you.
- 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.

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

Feel free to add more mods here

Nexus mods

Druids Den - Collectors Edition
Familiar Faces
Hook Immerse
Proper Potion Names
Key Input Framework
AH Hotkeys
Swift Potion Reborn
HT Casting Regeneration
Stat Control Panel
VioLens - A Killmove Mod

LL mods:

Radiantprostitution Tweaked
Creature Framework