Print

Please login or register.
1 Hour 1 Day 1 Week 1 Month Forever
Login with username, password and session length

[Nagidal]

I am starting to learn about the Lua API to DFHack. Whenever a Lua script wants to access some information from the game, it finds it somewhere in the df global object.

What I don't quite understand is how do you know where to find which things. The structure of the df global object is defined in the df-structures xmls. (The way how this formal structure description works is laid out in the Data Structure Definition Syntax).

It seems to me that all top-level type definitions, no matter which one of the xmls they are mentioned in, are found directly under df.

Example1: df.units.xml mentions a top-level <struct-type type-name='unit_preference'>. The way to access this struct from the Lua API is df.unit_preference, rather than df.units.unit_preference

Example2: df.globals.xml mentions a top-level <enum-type type-name='weather_type' base-type='int8_t'>. The way to access this enum from the Lua API is df.weather_type, rather than df.globals.weather_type

So obviously, the the reason why you guys split the copious amounts of top-level types, objects or tables into different xml files is purely to keep those together, which are often used together? One such xml file with structure definition does not represent a certain node somewhere in the df object tree, right?

[Warmist]

• df.global is root of it all
• df.sth is usually a type (e.g. df.unit or df.item)
• df.global.world is where most of the stuff lives
• types sometimes have ".find" method and other useful stuff

[PatrikLundell]

There is some DFHack stuff, found, logically, with a root of dfhack.
Apart from df.global.world where most of the stuff is, there's also df.global.ui (some of the stuff would have fit better in world, in my view, but it's Toady's organization) and
df.global.gview.view (to get at info in the main DF UI screens, but not the side views).

The below is probably info you have no need for for the time being...

Also note that some things are dynamic in that they contain different things depending on circumstances. The big one here is the df.global.world.world_data.region_details, which contains mid tile map level info in the current world tile in pre embark, and the embark tile plus the surrounding 8 world tiles when in a fortress. As you change the pre embark focus, this data structure is generated anew from the seed for the new current world tile. Hacking this info and changing focus and returning has the info erased (but embarking while in a hacked world tile will preserve the hacked info's effects within the embark, but not the rest of the region). Similarly, the embark info is generated from seeds at embark. There's also some info that's loaded (from file?) only when required, such as "features", which include stuff like candy spires and magma pools on a general level. That structure is particularly insidious in that it's loaded as "feature shell" (16*16 world tile blocks) at the tip level when required, so trying to access the info when it's not loaded will cause DF to crash.

[mifki]

It seems to me that all top-level type definitions, no matter which one of the xmls they are mentioned in, are found directly under df.

Of course, these are just type definitions, apart from nested types (like df.unit.T_status), they are all in global namespace.

[Quietust]

The important thing to know is that "df.global" is where you find all of the global variables. Some of them are large structures (e.g. world, ui, enabler, gview, init), some are simple lists (ui_look_list, timed_events, ui_building_assign_items, etc.) and some are just simple values (gamemode, gametype, pause_state, *_next_id, debug_*, standing_orders_*, and so forth). Everything else, as noted above, is a type, and types can be structures/classes, enumerations, and bitfields.