A Guide To Grim Dawn's Lua Engine

[atom0s]

This is a guide to Grim Dawn's current Lua engine. This post is based on the current game version: B24

Dumping The Games Lua State
To dump the Lua state, you will need my GDHook project from here:
viewtopic.php?f=9&t=50

Next you will need my statedumper.lua script, which you can get here:
https://www.dropbox.com/s/8w6av2xjccsxr ... r.lua?dl=0

You must place this Lua script here:
<Path to Your GDHook Folder>\GDHook\Plugins\GrimLua\statedumper.lua

Once installed, launch the game and enter a single player game. You must be in game for this to work, you cannot do this at the menu screen because the game DOES NOT create a Lua state until you are playing.

Now that you are in game, open up GDHooks console via '~' (or whatever you may have changed it to and enter the following commands:
/load grimlua
/gluascript statedumper.lua

If everything is done correctly, you should see:


Once finished you can find the newly dumped information here:
<Path To Grim Dawn>\luadump\

For example:
C:\Program Files (x86)\Steam\SteamApps\common\Grim Dawn\luadump

This Lua script dumper I wrote creates two file types:
- main.txt : The main global table information. (Functions, properties, and tables.)
- tables\<name>.txt : Information specific to that given table.

Please note:

You need to manually create a few folders for the statedumper.lua script to work.

Go into your Grim Dawn folder and create a folder named: luadump
Go inside of the luadump folder and create another folder named: tables

Then run the script and it will dump into that new luadump folder.

[atom0s]

Playing With The Local Player Object

One of the main objects that Grim Dawn's Lua makes use of is the local player entity. It is needed for various things such as checking if you have an item, checking if you have a specific quest objective, opening/unlocking doors, etc. With that there are various functions that we can mess with.

You can obtain the local player entity from the 'Game' table like this:

Code: Select all

local me = Game.GetLocalPlayer();

Now that we have our player entity we can make use of the functions that the player class (and its base classes) expose.
Below are some of the functions that we can make use of:

Misc Player Functions

• Player.AdjustMoney(entity, amount);
  Player.Attack(entity, entity_id);
  Player.GetCoords(entity);
  Player.GetFaction(entity, faction_name);
  Player.GetLevel(entity);
  Player.GetPlayerName(entity);
  Player.GiveExperience(entity, amount);
  Player.GiveLevels(entity, amount);
  Player.GiveSkillPoints(entity, amount);
  Player.Kill(entity);
  Player.PlaySound(entity, sound_id);
  Player.Say(entity, tag_text);
  Player.SetCoords(entity, world_coords);
  Player.Turn(entity, vector);

Item Related Player Functions

• Player.DestroyItem(entity, item_string);
  Player.GiveItem(entity, item_string, amount, unknown_bool);
  Player.HasItem(entity, item_string, amount, unknown_bool);
  Player.TakeItem(entity, item_string, amount, unknown_bool);

Quest / Token Related Player Functions

• Player.AnyoneHasToken(entity, token_name);
  Player.GiveToken(entity, token_name);
  Player.HasToken(entity, token_name);
  Player.RemoveToken(entity, token_name);
  Player.ServerHasToken(entity, token_name);
  
  Player.CompleteQuest(entity, quest_id, task_id);
  Player.GetQuestState(entity, quest_id);
  Player.GetQuestTaskState(entity, quest_id, task_id);
  Player.GrantQuest(entity, quest_id, task_id);

Object Related Functions

• Player.Destroy(entity);
  Player.GetId(entity);
  Player.GetName(entity);
  Player.IsReloaded(entity);
  Player.NetworkEnable(entity);

Putting It All Together
With what we know now, we can do things like this:

Code: Select all

-- Obtain the local player..
local me = Game.GetLocalPlayer();

-- Give our player 40 levels..
me:GiveLevels(40);

-- Give our player a lot of money..
me:AdjustMoney(999999999);

-- Give our player skill points..
me:GiveSkillPoints(999999999);

This script will force our player to level 40, give us 999,999,999 iron, and gives us 999,999,999 skill points to make use of.

[atom0s]

Obtaining Items Through Lua

A nice and fun thing we can do is acquire items through Lua. To do that we must make use of the following:
Player.GiveItem(entity, item_string, amount, unknown_bool);

However this is not entirely straight forward. GiveItem takes an item_string as an argument but this is a database record.
That means Grim Dawn wants a full path name of the item that is in the database.arz file.

You can easily obtain these paths by dumping the .arz file back to normal files on disk.

You can use my grimarz project to do this. See here for more info:
viewtopic.php?f=9&t=5

Once you have the database file extracted you can now browse the various records from within it. Now that it is extracted we can get the proper paths to use with the GiveItem function (and the other item functions for that matter).

Lets use a bonus item for our example. Open up the extracted database files and navigate to:
extracted\records\items\bonusitems\


Here we see two files both of which are .dbr (database records). These are valid for the item functions. So for example, lets give ourselves a bonus_summonwisp.dbr. To do that we can use:

Code: Select all

-- Obtain the local player..
local me = Game.GetLocalPlayer();

-- Give ourself a specific item..
me:GiveItem('records/items/bonusitems/bonus_summonwisp.dbr', 1, false);

And the result is:


You can change the 1 to any number. That is the amount of items it will give you. The 'false' I am unsure of at this time, I am thinking it is something to do with overwriting items or something but not entirely sure. Setting it between true and false seems to do nothing as far as I can tell. So use it with caution!

If you want to check out the DLC items now, you can give yourself them:
'records/items/bonusitems/bonus_burrwitchbrew.dbr'
'records/items/bonusitems/bonus_summonwisp.dbr'
'records/items/transmutes/dlc_head_powderedwig.dbr'
'records/items/transmutes/dlc_torso_swashbucklerscoat.dbr'
'records/items/transmutes/transmute_powderedwig.dbr'
'records/items/transmutes/transmute_swashbucklerscoat.dbr'

[immorrr]

Thanks alot for your hard work, this really helps!

Still i couldnt figure out how to set coords yet

[immorrr]

could you help me how to exactly set the players coordinates (teleport)?

what i was trying is:

Code: Select all

local me = Game.GetLocalPlayer()
me.SetCoords(me, 'coordinates');

i am not sure which format to use for 'coordinates'...

[immorrr]

No idea?

[dnoth]

Try Player.GetCoords to set a variable w/ the current coordinates, then later calling Player.SetCoords with that variable. I tried that, and the screen briefly flashes as if it did something, but the player character stays in its current spot.

[atom0s]

You cannot update your own position from Lua, the game will force you back to your previous position.

[dnoth]

Another quirk I've found... while giving myself components, then combining them, the completed component always has the same completion bonus. I have 12 Amber that all have +4% physical damage as their bonus Same occurs when giving yourself a relic, the stats & bonus are static rather than randomized. I haven't tried any actual gear yet, but I'm guessing it'll be a similar result.

Anyway... love the utility. Until official mod tools are released that hopefully will make respec'ing easier, it's great being able to freely mess around with various character builds. Getting to 40 isn't hard, but man is it grindy. So, thanks for this tool.

I did find that setting the last argument to GiveItem to True is the difference between getting a component fragment and a complete component. So :

Player.GiveItem(me,'records/items/materia/compa_rigidshell.dbr',4,false) <--- gives 4 rigid shell fragments
Player.GiveItem(me,'records/items/materia/compa_rigidshell.dbr',4,true) <--- gives 4 rigid shells

The caveat here being that the complete component has no completion bonus. Useful for crafting, though.

[immorrr]

Try Player.GetCoords to set a variable w/ the current coordinates, then later calling Player.SetCoords with that variable. I tried that, and the screen briefly flashes as if it did something, but the player character stays in its current spot.

You cannot update your own position from Lua, the game will force you back to your previous position.

This is due to the memory address being used is not the one used for "setting" a chars position, is looks like the used address calculates the current position in any way...
After searching a while with CE i was able to find the addresses which can be used for setting a chars x/y/z position. Badly i wasnt able to retrieve a working ptr for those addresses with CE, i think i need to fire up my IDA again...

Another quirk I've found... while giving myself components, then combining them, the completed component always has the same completion bonus. I have 12 Amber that all have +4% physical damage as their bonus Same occurs when giving yourself a relic, the stats & bonus are static rather than randomized. I haven't tried any actual gear yet, but I'm guessing it'll be a similar result.

You're guessing correctly