Trihan

Speedy Scripter
Veteran
Joined
Apr 12, 2012
Messages
3,713
Reaction score
2,830
First Language
English
Primarily Uses
RMMZ
Ahead of the new Jump into Javascript, I've noticed a fair number of times before that many people seem to struggle with the connection between the global $dataxxxx objects and the editor's database, so I thought I would provide a comprehensive list of those classes and the properties they map to.

I'll be using MZ for this, so some of the items may not exist in MV, but they're almost all the same.

One thing to note is that you don't need to worry about array indexes starting at 0, because the way the RPG Maker developer set up the data, every object like this has its first entry as "null" so that no index offset is needed.

When describing the element -> code mapping, I'll use the format "element (explanation of where in the database it is): propertyreference (any additional things to know)". This means that referring to it in a script will be $dataActors[actorid].propertyreference.

Actors

The actors in your database map to the $dataActors array. To reference a specific actor, the element index is the same as the actor ID i.e. to look at a piece of data for actor 3, you'd use $dataActors[3].

ID (the index of the actor's entry in the tab): id
Name: name
Nickname: nickname
Class: classId
Initial level: initialLevel
Max level: maxLevel
Profile: profile
Face name (the graphic chosen for the actor's face): faceName
Face index (the index, starting at 0, of the specific face in the graphic to use): faceIndex
Character name (the graphic chosen for the actor's walking graphic): characterName
Character index (the index, starting at 0, of the specific walking graphic to use): characterIndex
Battler name (the graphic to use as the actor's battler)
Initial equipment: equips (this is an array for each equipment slot containing the ID of the weapon/armour item that will be in that slot at the beginning of the game, or 0 if the slot is empty. For example, in a game using the standard extended default database with the slots "Weapon", "Shield", "Head", "Armour" and "Accessory", for an actor who starts out with a Short Sword, <none>, Leather Cap, Cloth Armour and <none>, the array with be [1, 0, 52, 8, 0].
Traits: traits (see section on Traits, as this is quite involved)
Note: note (this is the field where notetags for plugins are stored)
Meta: meta (see section on Meta)

Classes

Classes map to $dataClasses, and are accessed the same way as actors ($dataClasses[3] references the 3rd class)

ID (the index of the class's entry in the tab): id (this will match up to the classId from the actor to define which class they have)
Name: name
Exp curve: expParams (This is a 4-element array consisting of base value, extra value, acceleration A, acceleration B, for example [30, 20, 30, 30] for default Swordsman. The exact formula used to determine total exp for each level is Math.round(base * (Math.pow(level - 1, 0.9 + acc A / 250)) * level * (level + 1) / (6 + Math.pow(level, 2) / 50 / acc B ) + (level - 1) * extra), so the exp required for level 1 -> 2 is Math.round(30 * (Math.pow(2 - 1, 0.9 + 30 / 250)) * 2 * (2 + 1) / (6 + Math.pow(2, 2) / 50 / 30) + (2 - 1) * 20), which works out to 50. Replace the 2s with 3s and you'll get 162, then 366, and so on until level 99. If you look at the "Total" tab of the exp curve setting, you'll see the values match)
Parameter curves: params (this is an 8-element array where each element represents a parameter: 0 for max HP, 1 for max MP, 2 for attack, 3 for defence, 4 for magic attack, 5 for magic defence, 6 for agility and 7 for luck), and each element is itself a 99-element array containing the value for that parameter at each level. Accessing a 2-dimensional array like this is as simple as appending a second index reference, so to look at what the attack power is at level 12 for class 5, it'd be $dataClasses[5].params[2][11]. Note that this does have to be 0-indexed because element 0 represents level 1)
Learnable Skills: learnings (This is an array containing an element for each learnable skill. Each element is an object with three properties: level, note, and skillId. For example, if the class learns Strong Attack at level 5, its entry will be { level: 5, note: "", skillId: 172 }. Note is almost never used; it serves no purpose in the engine and as far as I'm aware no plugin has ever utilised it.)
Traits: traits (see section on Traits)
Note: note
Meta: meta (see section on Meta)

Skills

Skills map to $dataSkills, and again are accessed via index. This is the case for all of these, so I won't say it again.

ID (the index of the skill's entry in the tab): id (this will match up with skillId in a class's learnings element)
Name: name
Icon: iconIndex (this starts at 0, which will be the blank icon at the top-left of the iconsheet)
Description: description
Skill type: stypeId (this will match up with an ID from the Skill Types list in the Types tab)
MP cost: mpCost
TP cost: tpCost
Scope: scope (0 for None, 1 for Enemy - One, 2 for Enemy - All, 3 for Enemy - Random - 1, 4 for Enemy - Random - 2, 5 for Enemy - Random - 3, 6 for Enemy - Random - 4, 7 for Ally - One - Alive, 8 for Ally - All - Alive, 9 for Ally - One - Dead, 10 for Ally - All - Dead, 11 for User, 12 for Ally - One - Unconditional, 13 for Ally - All - Unconditional, 14 for Enemy & Ally - All. Note that this will differ slightly for MV as it doesn't have unconditional or enemy & ally)
Occasion: occasion (0 for Always, 1 for Battle Screen, 2 for Menu Screen, 3 for Never)
Speed: speed
Success: successRate (this is represented as the actual percentage value, not a decimal. So a 100% success chance is stored in the variable as 100)
Repeat: repeats
TP Gain: tpGain
Hit Type: hitType (0 for Certain Hit, 1 for Physical Attack, 2 for Magical Attack)
Animation: animationId (this will match up with an ID from the Animations tab)
Message: message1, message2 (message1 stores the top line, message2 the bottom one. There's also a messageType property but nothing uses it, nothing in the editor sets it and it isn't referenced anywhere. It seems to always have a value of 1 in the default data)
Required Weapon: requiredWtypeId1, requiredWtypeId2 (0 for None; any other value will match up with the ID number of a weapon type from the Weapon Types list in the Types tab)
Damage: damage (all of the data is held in a single object with the following properties)
- type: 0 for None, 1 for HP Damage, 2 for MP Damage, 3 for HP Recover, 4 for MP Recover, 5 for HP Drain, 6 for MP Drain
- elementId: -1 for Normal Attack, 0 for None; any other value will match up with the ID number of an element from the Elements list in the Types tab)
- formula: the damage formula as a string
- variance: the percentage of variance, stored as a percentage value rather than a decimal
- critical: whether the skill can inflict critical hits: true for yes, false for no.
Effects: effects (see section on Effects)
Note: note
Meta: meta

Items

Items map to $dataItems.

ID: id
Name: name
Icon: iconIndex
Description: description
Item Type: itypeId (1 for Regular Item, 2 for Key Item, 3 for Hidden Item A and 4 for Hidden Item B ).
Price: price
Consumable: consumable (whether the item will be removed from inventory when used: true for yes, false for no)
Scope: scope (see skills for the list)
Occasion: occasion (0 for Always, 1 for Battle Screen, 2 for Menu Screen, 3 for Never)
Speed: speed
Success: successRate
Repeat: repeats
TP Gain: tpGain
Hit Type: hitType (0 for Certain Hit, 1 for Physical Attack, 2 for Magical Attack)
Animation: animationId (this will match up with an ID from the Animations tab)
Damage: damage (see skills for object breakdown)
Effects: effects (see section on Effects)
Note: note
Meta: meta

Weapons

Weapons map to $dataWeapons.

ID: id
Name: name
Icon: iconIndex
Description: description
Weapon Type: wtypeId (this will match up with an ID from the Weapon Types list in the Types tab)
Price: price
Animation: animationId
Parameter Changes: params (this is an 8-element ID where each element contains the amount by which each parameter will change when the weapon is equipped: 0 for Max HP, 1 for Max MP, 2 for Attack, 3 for Defence, 4 for M. Attack, 5 for M. Defence, 6 for Aility and 7 for Luck)
Traits: traits (see section on Traits)
Note: note
Meta: meta

Weapons also have an etypeId (equipment type ID) property, but it's always 1 for Weapon.

Armors

Armours map to $dataArmors.

ID: id
Name: name
Icon: iconIndex
Description: description
Armor Type: atypeId (0 for None; any other value will match up with an ID from the Armor Types list in the Types tab)
Price: price
Equipment Type: etypeId (will never be 1 as that's for weapons; 2 onwards will match up with the corresponding ID from the Equipment Types list in the Types tab)
Parameter Changes: params (same as Weapons)
Traits: traits (see section on Traits)
Note: note
Meta: meta

Enemies

Enemies map to $dataEnemies.

ID: id
Name: name
Battler: battlerName/battlerHue (the former is the filename of the graphic, the latter is the Hue setting from 0 to 360)
Max HP/Max MP/Attack/Defence/M.Attack/M.Defence/Agility/Luck: params (this is an 8-element array, same as the others seen for parameters, where each element is the value for the param. For example, an enemy with 100 max HP, 200 max MP, attack 25, defence 20, mat of 20, mdf of 20, agility of 20 and luck of 20 have a params array of [100, 200, 25, 20, 20, 20, 20, 20])
EXP: exp
Gold: gold
Drop Items: dropItems (this is an array with an element for each item the enemy can drop; each element is an object with the following properties)
- kind: 0 for none, 1 for item, 2 for weapon and 3 for armour.
- dataId: The ID of the object from that kind.
- denominator: Represents the X of the "1 in X" chance of the item dropping. For example, if the drop rate is 1/10, denominator will be 10.
So to have an enemy drop a Potion with a 1/5 chance, the object will be { kind: 1, dataId: 7, denominator: 5 }.
Action Patterns: actions (this is an array with an element for each possible skill the enemy can use; each element is an object with the following properties)
- skillId: The matching ID from the Skills tab for the skill to use
- rating: The likelihood of the skill being used (note that any rating more than 3 below the highest will never be used at all)
- conditionType: 0 for Always, 1 for Turn, 2 for HP, 3 for MP, 4 for State, 5 for Party Level, 6 for Switch
- conditionParam1: For Turn, this is "A" (the starting turn for executing the skill). For HP and MP, it's the lower percentage as a decimal. For State, it's the ID of the state. For Party Level, it's the number to use as the highest party level for execution. For Switch, it's the switch ID.
- conditionParam2: For Turn, this is "B" (the number of turns to skip between uses). For HP and MP, it's the higher percentage as a decimal. For State, Party Level, and Switch, this isn't used.
Traits: traits (see section on Traits)
Note: note
Meta: meta

Troops

Troops map to $dataTroops.

ID: id
Name: name
Members: members (This is an array with an element for each enemy in the battle; each element is an object with properties enemyId, x, y and hidden. enemyId is the ID from the Enemies tab, x and y are the coordinates for displaying the battler, and hidden maps to the "Appear Mid-Battle" flag: true for yes, false for no)
Troop events: pages (this is an array with an element for each page of events. Breaking down the structure beyond that is a complicated endeavour that could warrant its own article, so I won't go further into it here)

States

States map to $dataStates.

ID: id
Name: name
Icon: iconIndex
Restriction: restriction (0 for None, 1 for Attack an enemy, 2 for Attack anyone, 3 for Attack an ally, 4 for Cannot move)
Priority: priority (determines which icons take precedence in the display when multiples are applied)
[SV] Motion: motion (0 for Normal, 1 for Abnormal, 2 for Sleep, 3 for Dead)
[SV] Overlay: overlay (0 for None, 1 for Poison, 2 for Blind, 3 for Silence, 4 for Rage, 5 for Confusion, 6 for Charm, 7 for Sleep, 8 for Paralysis, 9 for Curse, 10 for Fear)
Remove at Battle End: removeAtBattleEnd (true if checked, false if unchecked)
Remove by Restriction: removeByRestriction (true if checked, false if unchecked. If this is checked, applying a state with any restriction but 0 will remove this one)
Auto-removal Timing: autoRemovalTiming (0 for None, 1 for Action End, 2 for Turn End)
Duration in Turns: minTurns/maxTurns (minTurns is for the first input, maxTurns for the second)
Remove by Damage: removeByDamage (true if checked, false if unchecked)
Damage chance: chanceByDamage (percentage chance that taking damage will remove the state)
Remove by Walking: removeByWalking (true if checked, false if unchecked)
Steps: stepsToRemove
Message: message1/message2/message3/message4 (message1 is for when an actor is inflicted with the state, message2 for when an enemy is inflicted with it, message3 for when the state persists between turns, and message4 for when the state is removed. There's also a messageType but it isn't used and nothing in the editor changes it)
Traits: traits (see section on Traits)
Note: note
Meta: meta

Animations

Animations map to $dataAnimations.

ID: id
Name: name
Display Type: displayType (0 for For each target, 1 for Center of all targets, 2 for Center of the screen)
Align Bottom: alignBottom (true if checked, false if unchecked)
Filename: effectName (the name of the Effekseer file)
Scale: scale (the percentage by which to scale the effect)
Speed: speed (the percentage of the original speed to run the effect at)
Rotation: rotation (this is an object with properties x, y and z, -360 to 360 degrees for each. So to rotate the effect by 15 degrees on the X, 0 degrees on the Y and -50 degrees on the Z, the object will be { x: 15, y: 0, z: -50 }.)
Offset X: offsetX
Offset Y: offsetY
Sound: soundTimings (This is an array of sound effects in the animation. Each element is an object with properties frame and se. frame is the frame of the animation to play the sound at, and se is another object with properties name, pan, pitch and volume. For example, to play the sound "Blow1" on the first frame panned in the center at 100% pitch and 90% volume, the object will be { frame: 0, se: { name: "Blow1", pan: 0, pitch: 100, volume: 90 } }. Note that the frame in the object will be 1 less than the chosen value in the dialog)
Flash: flashTimings (This is an array of flash effects in the animation. Each element is an object with properties frame, duration and color. frame is the frame of the animation to start the flash at, duration is the number of frames to flash for, and color is an array with 4 elements, for the R, G, B and alpha components of the flash colour)

Tilesets

Tilesets map to $dataTilesets.

ID: id
Name: name
Mode: mode (0 for World Type, 1 for Area Type)
Images: tilesetNames (this is a 9-element array with elements mapping to A1, A2, A3, A4, A5, B, C, D, and E. Each element is the string filename of the tileset graphic to use in that slot)
Tile settings: flags (this is an 8192-element array representing the passage/ladder/bush etc. settings for each tile. A full explanation of how the flags array works is also beyond the scope of what I'm doing here, so that'll have to suffice)
Note: note
Meta: meta

Common Events

Common events map to $dataCommonEvents.

ID: id
Name: name
Trigger: trigger (0 for None, 1 for Autorun, 2 for Parallel)
Switch: switchId
Contents: list (as with troop events, a breakdown of this is a subject for a more focused article)

System 1
System 2
Types
Terms


Everything in both system tabs, Types and the Terms tab map to $dataSystem.

Game Title: gameTitle
Starting Party: partyMembers (this is an array where each element contains the ID of the actor in that party slot)
Currency: currentUnit
Window Color: windowTone (a 4-element array containing the R, G, B and alpha components of the tone. Note that in the editor, you can only edit the RGB; alpha will always be 0)
Boat: boat (this is an object with the following properties)
- bgm: this is itself an object with properties name, pan, pitch and volume. It works the same way as the sound object in animations and gets its value from the "Boat" entry in Music.
- characterName: the graphic name chosen for "Boat".
- characterIndex: the specific index on that graphic.
- startMapId: the ID of the map this vehicle starts on. This and the start coordinates are taken from the "Starting Positions" setting for the boat, which will also be updated if the player sets the starting location from the right-click menu in event edit mode.
- startX: The X coordinate the vehicle starts on.
- startY : The Y coordinate the vehicle starts on.
Ship: ship (this is an object with the same properties as boat)
Airship: airship (this is an object with the same properties as boat)
Player start: startMapId/startX/startY
Title Screen: title1Name/title2Name (title1Name is the main background image, while title2Name is for the "overlay")
Draw Game Title: optDrawTitle (true if checked, false if unchecked)
Command Window: titleCommandWindow (this is an object with properties background, offsetX and offsetY. background is 0 for Window, 1 for Dim and 2 for Transparent)
Battle Screen: optSideView (true for Side-view, false for Front-view)
Battle System: battleSystem (0 for Turn-based, 1 for Time Progress (Active) and 2 for Time Progress (Wait))
Options: optTransparent/optFollowers/optSlipDeath/optFloorDeath/optDisplayTp/optExtraExp/optKeyItemsNumber/optAutosave (these just correspond to the respective checkboxes)
Music: titleBgm/battleBgm/victoryMe/defeatMe/gameoverMe (these are objects with the same settings as other BGM/MEs we've covered)
Sound: sounds (this is a 24-element array where each element is an object with the same sound/music properties: name, pan, pitch and volume)
Menu Command: menuCommands (this is a 6-element array where each element is true or false depending on whether you want the Item/Skill/Equip/Status/Formation/Save commands in the menu)
Item Categories: itemCategories (this is a 4-element array where each element is true or false depending on whether you want the Item/Weapon/Armor/Key Item categories to be listed in the item scene)
[SV] Magic Skills: magicSkills (this is an array where each element is the ID of a skill type you want the engine to consider "magic" for the purposes of differentiating physical/magical skills in battle)
[SV] Attack Motions: attackMotions (this is an array containing an element for each weapon type defined in the Types tab. Each element is an object with properties type and weaponImageId. type is 0 for Thrust, 1 for Swing and 2 for Missile. weaponImageId is 0 for None, 1 for Dagger, 2 for Sword, 3 for Flail, 4 for Axe, 5 for Whip, 6 for Staff, 7 for Bow, 8 for Crossbow, 9 for Gun, 10 for Claw, 11 for Glove, 12 for Spear, 13 for Mace, 14 for Rod, 15 for Club, 16 for Combat Chain, 17 for Futuristic Sword, 18 for Iron Pipe, 19 for Slingshot, 20 for Shotgun, 21 for Rifle, 22 for Chainsaw, 23 for Railgun, 24 for Stun Rod, 25 for User-defined 1, 26 for User-defined 2, 27 for User-defined 3, 28 for User-defined 4, 29 for User-defined 5 and 30 for User-defined 6)
Advanced Settings: advanced (this is an object with the following properties)
- gameId
- screenWidth
- screenHeight
- uiAreaWidth
- uiAreaHeight
- mainFontFilename
- numberFontFilename
- fallbackFonts (a single string with each font name separated by commas)
- fontSize
Elements: elements (An array of strings for each element name, starting with a blank string at index 0)
Skill Types: skillTypes (An array of strings for each skill type, starting with a blank string at index 0)
Weapon Types: weaponTypes (as above)
Armor Types: armorTypes
Equipment Types: equipTypes
Terms: terms (this is split up further into...)
- basic (this is a 10-element array containing the following elements: level, level abbreviation, HP, HP abbreviation, MP, MP abbreviation, TP, TP abbreviation, Exp, Exp abbreviation)
- commands (this is a 26-element array containing the following elements: Fight, Escape, Attack, Guard, Item, Skill, Equip, Status, Formation, Save, Game End, Options, Weapon, Armor, Key Item, Equip, Optimize, Clear, New Game, Continue, null, To Title, Cancel, null, Buy and Sell. I'm not 100% sure what the null entries are for, but I suspect there were originally a couple of extra terms that for whatever reason the devs removed)
- messages (unlike the previous two, this is an object with the following keys, each of which is a string: actionFailure, actorDamage, actorDrain, actorGain, actorLoss, actorNoDamage, actorNoHit, actorRecovery, alwaysDash, autosave, bgmVolume, bgsVolume, buffAdd, buffRemove, commandRemember, counterAttack, criticalToActor, criticalToEnemy, debuffAdd, defeat, emerge, enemyDamage, enemyDrain, enemyGain, enemyLoss, enemyNoDamage, enemyNoHit, enemyRecovery, escapeFailure, escapeStart, evasion, expNext, expTotal, file, levelUp, loadMessage, magicEvasion, magicReflection, meVolume, obtainExp, obtainGold, obtainItem, obtainSkill, partyName, possession, preemptive, saveMessage, seVolume, substitute, surprise, touchUI, useItem and victory)
- params (this is a 10-element array containing the following elements: Max HP, Max MP, Attack, Defence, M. Attack, M. Defence, Agility, Luck, Hit and Evasion)

$dataSystem also contains a few other things:

editMapId: the ID of the map currently selected in the editor
locale: the system's locale setting
switches: an array containing the names of each switch, starting with a blank string at index 0
variables: an array containing the names of each variable, starting with a blank string at index 0
testBattlers: an array for the battlers which will be used in test battle. Each element is an object with properties actorId, level and equips. equips is an array containing the ID of each piece of equipment in each slot.
testTroopId: The ID of the troop to be used in test battle.
versionId: The game version. This is regenerated each time the game is saved.

Map

There are two data classes pertaining to maps. The first is $dataMap and contains the data of the currently-loaded map. If the player isn't on a map, this is null.

Display Name: displayName (the name to be used when entering the map if that option is enabled)
Tileset: tilesetId (the ID of the tileset to use on the map)
Width: width
Height: height
Scroll Type: scrollType (0 for No Loop, 1 for Loop Vertically, 2 for Loop Horizontally or 3 for Loop Both)
Enc. Steps: encounterStep
Autoplay BGM: autoplayBgm (true if checked, false if unchecked) and bgm (same properties as other sound objects)
Autoplay BGS: autoplayBgs (true if checked, false if unchecked) and bgs
Specify Battleback: specifyBattleback (true if checked, false if unchecked)
Battleback: battleback1Name/battleback2Name
Disable Dashing: disableDashing
Parallax image: parallaxName
Loop Horizontally: parallaxLoopX
- Scroll: parallaxSx
Loop Vertically: parallaxLoopY
- Scroll: parallaxSy
Show in the Editor: parallaxShow (true if checked, false if unchecked)
Note: note
Meta: meta
Encounters: encounterList (this is an array with an element for each troop that can be encountered. Each element is an object with properties troopId, weight and regionSet. troop ID is the ID of the troop, weight is the chance of encountering it. regionSet is an array of the regions you can encounter the troop in; if the range is "Entire Map" the array will be empty)

$dataMapInfos is an array of high-level map data, with the index 0 element being null. Each element is an object with properties id, expanded, name, order, scrollX, scrollY and parentId.

Traits

Each trait in an object's traits section is represented with an object which has the properties code, dataId and value.

code looks complicated, but it's actually really simple. The first digit is the tab the trait is on, and the second digit is the number of the radio button for that trait. So "Attack State" has the code 32 because it's on tab 3 and it's item #2 on that tab.

dataId represents the first piece of data for the trait: an element ID, state ID, parameter ID, skill type ID etc.

value represents the second piece of data for the trait: it's used for Element Rate, Debuff Rate, State Rate, Parameter, Ex-Parameter, Sp-Parameter and Attack State. In each case it represents a percentage: whether that's additive or multiplicative depends on the trait, but you can tell which is which by whether the editor dialog has a + or a * next to the input. If it's not used, it defaults to 1.

So let's say we want a trait which adds the skill Dual Attack. The object for that trait will be:

{ code: 43, dataId: 12, value: 1 } (tab 4, item 3)

Allowing the object to equip heavy armour:

{ code: 52, dataId: 4, value: 1 } (tab 5, item 2)

50% chance of being blinded:

{ code: 13, dataId: 5, value: 0.5 } (tab 1, item 3)

As you can see, traits initially look really intimidating but they're ridiculously easy to translate into code objects.

Effects

Effects are very similar to traits. The only difference is that effects have two value properties: value1 and value2. The code works exactly the same way: first digit is the tab, second digit is the item number. So a Potion which heals 500 HP would have the effect

{ code: 11, dataId: 0, value1: 0, value2: 500 }

An item that recovers 20% MP plus 50 would be

{ code: 12, dataId: 0, value1: 0.2, value2: 50 }

Meta

Meta is a calculated property available to any object from a tab with a note field which converts any notetag in the note field to an object: for example, if you enter a note of <notefield: value> the meta object will contain the entry "notefield:value". If notefield is a single word, you can also reference meta.notefield to get its value; otherwise, it needs to be enclosed in square brackets and quoted. For example, if actor 3 has <startRage:100> in their notefield, then $dataActors[3].meta.startRage will return 100, whereas for <starting rage: 100> you'd have to use $dataActors[3].meta["starting rage"]. This is case-sensitive, so "starting rage" and "Starting rage" are two different properties)=.
 
Last edited:

Latest Threads

Latest Posts

Latest Profile Posts

Tiamat-86 wrote on Andar's profile.
tfw just trying to help and get yelled at. /comfort
:LZSooo: Gotcha Gotcha Games... have launched an official discord server for RPG Maker. :LZSooo:

doodled a poring today :kaoluv:
uc
Fire-Emblem Style Level Up System, Boost on Class Change, And Animated Arrows | RPG Maker News #115

Why keyboards don't sleep? Because they have two shifts.

Forum statistics

Threads
113,945
Messages
1,078,583
Members
148,050
Latest member
dramacoolanetamak
Top