Skip to main content

Vault

MySims Kingdom
MySims Kingdom Logo

This information only applies to MySims Kingdom.

The vault is EA's AttribSys database. It holds most of MySims Kingdom's game data: characters, worlds and the objects placed in them, rewards, quests, Create-a-Sim parts, cameras and more.

A vault is a pair of files:

  • .vlt is the schema: types (primitive and compound) and classes (sets of typed fields).
  • .bin holds the collections: named records of one class. A collection can inherit from a parent collection of the same class, and it stores only the fields it sets.
This page is incomplete

Help by expanding it on GitHub.

Location​

The files are in GameData/Vaults/:

FileDescription
attribdb.vlt/attribdb.binThe vault the game loads (12,361 collections)
attribdbz.vlt/attribdbz.binA second vault, a subset of attribdb (10,291 collections)
attribdb.log, attribdbz.log, dbexporter.logExporter logs that list every type, class, field and collection as name[0xHASH]

Hashing​

Every id (type, member, class, field, collection) is the FNV32 hash of a name, computed over the lowercased ASCII name. There are two exceptions:

  • Text values hash their string without lowercasing.
  • Dynamic array elements use a derived key (see Dynamic arrays).

The names themselves are not stored in the vault. The exporter logs next to the vault files are the best source for them.

All values are little-endian.

.vlt (schema)​

0x28 bytes.

OffsetTypeNameNotes
0x00u32endian markeralways 1
0x04char[4]magicTLAV
0x08u32version3
0x0Cu32sizefile size minus this header (0x28)
0x10u32class_count
0x14u32type_count112 in the shipped vaults
0x18u8[16]reservedzeros

Types​

type_count type records follow, 40 bytes each:

OffsetTypeNameNotes
0x00u32typehash of the type name, e.g. EA.Reflection.Float
0x04u16sizebytes per value
0x06u16flagsunknown
0x08u16align
0x0Au16member_count0 for primitive types
0x0Cu8[28]runtimeu32 0 and three u64 pointers

Next come the members. For each type with member_count > 0, in type order, there are three parallel arrays with no padding between them:

TypeName
u32 × mmember name hashes
u16 × mmember type indices (into the type list)
u16 × mmember counts (element count; 0 or 1 = single)

At runtime, the three pointers in a type's runtime bytes point at these arrays.

Not every listed member is stored

In 14 compound types, the listed members take up more bytes than the type's size. Each handle member is followed by one plain UInt32 or UInt64 member for each member the handle has. Handle members are compounds such as Attrib.CollectionKey, MySims.AssetSpec, Attrib.RefSpec and MySims.HALString. The extra members are a runtime copy of what the handle resolves to and are not in the file. Skip them and the type fits its size exactly.

For example, MySims.PaintInfoEntry lists 7 members, but only 4 are stored:

OffsetTypeMeaning
0x00MySims.AssetSpecmaterial
0x08MySims.AssetSpecmaterial (the same, in every value seen)
0x10Attrib.CollectionKeypaint (default, coral, …)
0x14UInt32mesh index

Classes​

After the members come class_count × u64 class pointers (runtime only, ignored) and then the classes. Each class is a 40-byte header, its fields, and a trailer:

OffsetTypeNameNotes
0x00u32classhash of the class name, e.g. world
0x04u32unknownlow u16 is 0
0x08u16field_count
0x0Au16unknown
0x0Cu8[28]runtimeu32 0, a u64 pointer, two unknown u16, 12 zero bytes
0x28Field × field_countfields32 bytes each
…u8[]trailerunknown; runs in 8-byte steps to the next class header

Field (32 bytes):

OffsetTypeNameNotes
0x00u32fieldhash of the field name
0x04u32typetype hash
0x08u16sizebytes per element
0x0Au16flagssee below
0x0Cu16count
0x0Eu16align
0x10u16type_indexindex into the type list
0x12u8[14]runtimesix zero bytes and a u64 pointer

Field flags:

BitNameMeaning
0x0004INHERITABLEtaken from the parent collection when not set
0x0008ARRAY
0x0010FIXED_ARRAYwith ARRAY: a contiguous fixed array; without it, ARRAY is a dynamic array
0x0040READ_ONLY
0x0200BY_OFFSETthe entry holds an offset into the collection's data
0x0400FORCEDalways present (layout fields such as Position)

There is no marker for where a class ends. To find the next class header, step through the trailer 8 bytes at a time and look for this shape:

  • a nonzero u32,
  • u16 0 at +4 and u32 0 at +12,
  • and either a field count of zero at +8, or a first field whose type (at +44) is a known type hash.

The last class's trailer runs to the end of the file. Trailers hold pairs of u32. In most pairs the first word is hash("AttribClass") (0x26CF8A07) and the second is the hash of another class, apparently one that this class's fields refer to (e.g. fishingcursor → gesture, character → cas_asset and reward). Some pairs start with a different word (inventory: 0x6DA9159F, resource).

.bin (collections)​

Header​

Collections start at 0x144.

OffsetTypeNameNotes
0x00u32endian markeralways 1
0x04char[4]magicNIBV
0x08u32version5
0x0Cu32collection_count
0x10u32unknown
0x14u32—0
0x18u32unknown
0x1Cu32—0
0x20u32string_count
0x24u32—0
0x28u32unknown
0x2Cu8[]reservedzeros up to 0x144

Collections​

Collections are byte-packed, with no alignment between records:

OffsetTypeNameNotes
0x00u32collectionhash of the collection name
0x04u32vault
0x08u32classclass hash
0x0Cu32parentkey of the parent collection of the same class; 0 = none
0x10u16flagsunknown
0x12u16unknown
0x14u32—0
0x18u16unknown
0x1Au16unknown
0x1Cu16entry_countentries in use
0x1Eu16entry_capacityentries stored
0x20u16data_usedbytes of the data block that hold values
0x22u16data_capacitysize of the data block
0x24Entry × entry_capacityentriesthe first entry_count are used, the rest are padding
…u8[data_capacity]data

Entry (8 bytes):

OffsetTypeNameNotes
0x00u32fieldfield hash, or a dynamic array element key
0x04u8[4]valueinline value, or u16 offset; u16 count

String table​

The string table comes after the last collection:

TypeNameNotes
{u32 hash; u32 offset} × string_countindexhash of the text (case-sensitive), with exceptions (see below); offset is relative to the end of the index
NUL-terminated stringstextUTF-8
u8[]tailunknown, up to the end of the file (597,676 bytes in attribdb, none in attribdbz)

Not every hash is the hash of its text. In attribdb, 1,041 of 1,201 entries are. The other 160 are an empty string with hash 0 and 159 strings like [00030], whose hashes are something else.

Patterns​

ImHex patterns for both files. Load each pattern on its own file type.

.vlt​

The class trailers are found with the search described in Classes.

import std.core;
import std.mem;
import type.base;

struct VltHeader {
u32 endian;
char magic[4]; // TLAV
u32 version; // 3
u32 size;
u32 classCount;
u32 typeCount;
padding[16];
};

struct VltType {
type::Hex<u32> typeHash;
u16 size;
u16 flags;
u16 align;
u16 memberCount;
padding[28];
};

// The member arrays of one type. Empty for types without members.
struct VltMembers {
u32 typeIndex = std::core::array_index();
u16 m = std::mem::read_unsigned(0x28 + typeIndex * 40 + 0x0A, 2);
type::Hex<u32> names[m];
u16 typeIndices[m];
u16 counts[m];
};

struct VltField {
type::Hex<u32> field;
type::Hex<u32> typeHash;
u16 size;
type::Hex<u16> flags;
u16 count;
u16 align;
u16 typeIndex;
padding[14];
};

fn is_known_type(u32 hash) {
u32 typeCount = std::mem::read_unsigned(0x14, 4);
for (u32 i = 0, i < typeCount, i = i + 1) {
if (std::mem::read_unsigned(0x28 + i * 40, 4) == hash)
return true;
}
return false;
};

fn is_class_start(u128 at) {
if (at + 48 > std::mem::size()) return true; // stop at the end of the file
if (std::mem::read_unsigned(at, 4) == 0) return false;
if (std::mem::read_unsigned(at + 4, 2) != 0) return false;
if (std::mem::read_unsigned(at + 12, 4) != 0) return false;
if (std::mem::read_unsigned(at + 8, 2) == 0) return true;
return is_known_type(std::mem::read_unsigned(at + 44, 4));
};

struct VltClass {
u32 classIndex = std::core::array_index();
type::Hex<u32> classKey;
u32 unk0;
u16 fieldCount;
u16 unk1;
padding[28];
VltField fields[fieldCount];
if (classIndex + 1 < std::mem::read_unsigned(0x10, 4))
u64 trailer[while(!is_class_start($))];
else
u8 trailer[while(!std::mem::eof())];
};

struct VltFile {
VltHeader header;
VltType types[header.typeCount];
VltMembers members[header.typeCount];
u64 classPointers[header.classCount];
VltClass classes[header.classCount];
};

VltFile file @ 0x00;

.bin​

Dynamic array elements need the logic described in Dynamic arrays, so this pattern shows the raw entries and data. Each string table entry shows the string it points at.

import std.mem;
import std.string;
import type.base;

struct BinHeader {
u32 endian;
char magic[4]; // NIBV
u32 version; // 5
u32 collectionCount;
u32 unk0;
u32;
u32 unk1;
u32;
u32 stringCount;
u32;
u32 unk2;
padding[0x144 - 0x2C];
};

struct Entry {
type::Hex<u32> field;
u8 value[4];
};

struct Collection {
type::Hex<u32> key;
type::Hex<u32> vault;
type::Hex<u32> classKey;
type::Hex<u32> parentKey;
type::Hex<u16> flags;
u16 unk0;
u32;
u16 unk1;
u16 unk2;
u16 entryCount;
u16 entryCapacity;
u16 dataUsed;
u16 dataCapacity;
Entry entries[entryCapacity];
u8 data[dataCapacity];
};

// An index entry, with the string it points at.
struct StringEntry {
type::Hex<u32> hash;
u32 offset;
u32 stringCount = std::mem::read_unsigned(0x20, 4);
std::string::NullString text @ addressof(parent) + stringCount * 8 + offset;
};

// The end of the text: past the string with the highest offset.
fn text_end(u128 index, u32 count) {
u128 base = index + count * 8;
u32 last = 0;
for (u32 i = 0, i < count, i = i + 1) {
u32 offset = std::mem::read_unsigned(index + i * 8 + 4, 4);
if (offset > last) last = offset;
}
u128 at = base + last;
while (std::mem::read_unsigned(at, 1) != 0) at = at + 1;
return at + 1;
};

struct StringTable {
u32 count = parent.header.stringCount;
StringEntry index[count];
u8 text[text_end(addressof(index), count) - $];
u8 tail[while(!std::mem::eof())];
};

struct BinFile {
BinHeader header;
Collection collections[header.collectionCount];
StringTable strings;
};

BinFile file @ 0x00;

Values​

To read a field's value, find its hash among the collection's entries. The field definition comes from the collection's class in the schema.

  • Inline (no BY_OFFSET flag): the value is the entry's 4 bytes. Only min(size, 4) bytes are used.
  • BY_OFFSET: the entry holds u16 offset; u16 count. The value is size bytes at offset in the data block. For an array, the value is count elements of size bytes each, stored back to back.
  • Dynamic arrays (ARRAY without FIXED_ARRAY): see below.
  • Undefined entries: some entries are neither a field of the class nor an array element. Their bytes run from the entry's offset to the next value's offset in the data. If the offset is at or past data_used, the value is the entry's 4 bytes.

Dynamic arrays​

The field's own entry holds u16 offset; u16 count. The elements are stored in one of two ways:

  • Inline, when the field has no element entries. There are count elements at offset, just like a fixed array (e.g. paint_kit.paints, ui_inventory.Item_List). Only treat an array as inline once every element entry in the collection has been placed in some array, because its elements may be among the unplaced ones.
  • As entries of their own. Each element is keyed fnv1(seed + "[%03d]") and holds u16 offset; u16 index. The FNV-1 state seed is continued over a suffix such as [007].

The seed is the same for every element of a field, but it is not the field's hash, and how it is derived is unknown. It can be recovered from the element keys by undoing the suffix with the inverse of the FNV prime. Then each seed can be matched to a field: look for collections where the elements under one seed fit exactly one array, meaning every index is below the array's count and the offsets step by the field's size.

Some arrays store index 0 for every element (island.Ambients, trevor_trevor's AlternateBodyModel). The seed recovered from index 0 is then wrong, and it can even match another field's seed. Some things that help:

  • Treat the elements under one seed as a group. A group belongs to an array whose count equals the group's size and whose element size equals the step between the group's offsets.
  • Arrays with the same count and element size take their groups in field order. Element blocks are stored in the data in field (hash) order.
  • Two elements whose indices differ in exactly one digit, at any position (0↔1, 0↔2, 4↔9, 10↔20, but not 12↔21), share a second seed under the swapped indices, because the index digits are XORed into the hash. So the key alone can't tell you the order of the elements. Use the stored indices when they differ, and otherwise the offsets.

Types​

Types by name (the name's hash is stored):

TypeValue
EA.Reflection.Boolu8 != 0
EA.Reflection.Int8 / Int16 / Int32 / Int64signed integer
EA.Reflection.UInt8 / … / UInt64unsigned integer
EA.Reflection.Floatf32
EA.Reflection.Textu32 hash into the .bin string table
Attrib.Types.Vector2 / Vector3 / Vector4 / Quaternion / FloatColourf32 × n
Attrib.CollectionKeyu32 collection key; the class is implied by the field
Attrib.RefSpec (0x65833771)u32 class; u32 collection
MySims.AssetSpec (0xD7CEB540)u64 resource instance (see Resource Key)
MySims.HALStringone member (0xA1954553) holding a record id in TextEAGLE/pc/eng_us.str (see Str)
GameObject.ComponentSettwo u64 bit sets
other compound typesstored members in order, each aligned to its type's align, with count elements

Inheritance​

If a collection doesn't store a field, look it up in its parent (the collection of the same class whose key is parent), and so on up the chain. For example, most placed objects inherit their Model from a definition collection.

Notable classes​

All of these are in attribdb.

ClassFieldsUse
worldModel (AssetSpec of the Level Bin), ChildRefSpecs (RefSpec array of placed objects), GameObjects_ScriptOwned, CharacterMapName / CritterMapName (toon ramp textures), CameraAngle, SafeStartPosition (a locator_node), Camera, InteriorWorldA level and everything placed in it. ChildRefSpecs can nest
any placed objectModel, Position (Vector3), Orientation (Quaternion for blocks, Euler degrees Y,X,Z otherwise), MaterialAssignments (MySims.PaintInfoEntry array), MotionPath, ScriptName (Text: the Lua class)Placing objects in a level
buildable_regionConnectedWorld (the interior's world), ChildRefSpecs (the building's blocks), ConnectedPortalDoors into interiors
portal, door blocksConnectedWorld, ConnectedPortal, Model, PositionDoors and portals between levels
characterHeadModel, BodyModel, AlternateHeadModel, AlternateBodyModel, AccessoryModel (models), Rig, FullName / ShortName (HALString), ScriptName, VoxGroup, Create-a-Sim fields (PlayerHeadModel, SkinToneIndex, …)Characters. VoxGroup names one of vox_group_a … vox_group_i, the letter of the character's voice banks (vo_<event>_<letter>.bnk)
cas_assetAssetInfo, HairMaterials, HatMaterials, BodyMaterials, SkinMaskCreate-a-Sim parts
cas_contextAssets, CASWorldThe Create-a-Sim screens and the parts they offer
locator_nodePositionNamed spots (start positions, schedule locations)
cameraInitialZoom, TargetHeight, TiltAngleMinZoom / TiltAngleMaxZoom, ZoomMinDistance / ZoomMaxDistance, FOVCamera settings (inherit from default)
rewardRelationshipCharacter, RelationshipPoints, RewardDialogTitle, RewardDialogMessageTask rewards

Unknowns​

  • .vlt: type flags, two u16 in each class header, and what the class trailers' pairs mean.
  • .bin: the header words at 0x10, 0x18 and 0x28; the collection vault and flags fields and three u16; the tail after the strings; the hashes of the string table's [000NN] entries.
  • How a dynamic array's element seed is derived from the field. It is not the hash of the field name, in either case, on its own or combined with the class.
  • MySims.CASAssetInfo member names.