JContainers by silvericed
Skyrim » Modders resources and tutorials
Added: 10/01/2014 - 10:23PM
Updated: 15/11/2015 - 01:00AM

16,754 Endorsements

3.2.5 Latest version

273,431 Unique D/Ls

354,947 Total D/Ls

701,753 Total Views

Uploaded by silvericed


Last updated at 1:00, 15 Nov 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 any complex data structures to and from JSON files preserving connections between them
- Embedded Lua - use real language, write Lua scripts, the script faster than Papyrus
- 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 entries (objects with fields), you have to imitate it by using arrays. Five entries of {"some text", number, Form} had to be done with two arrays - StringList & IntList & FormList
- No nested data structures. No way to create something like '64x64 grid, each cell containing an entry of type: {"grid name"-string, number, array referencing some other entries}', dump it into a file and read it back.


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 or 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 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.

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
Metachest - A Сross-Savegame Chest

Loverslab mods:

Radiantprostitution Tweaked
Creature Framework