Difference between revisions of "Loading Level Resources With Lua"

This is what has been found so far to add and/or modify level objects (during a level) and other level resources using a Lua script, along with brief descriptions of what these objects/resources do.

 

 

 

One way to change a level is to change what resources are loaded for the level; for example, loading a different "TriggerInstances" resource to load a different set of Triggers. One way to do this is to run code that alters the resTbl table used within the QueueResourcesForLoad() function. This function is initially defined in plain text in Journey.exe . (Research on this and the other functions in that ".lua" will probably reveal how to load completely customized resources from outside the .exe)

For example, if you execute this code, then whenever you define swapLevel as an internal level name ("Graveyard","Barrens",etc) the next level's resources will all be replaced with the ones from Level_''swapLevel'':

 

<div style="font-weight:bold;line-height:1.6;">Example code mod for swapping resources between levels</div>

 

  <nowiki>swapLevel = ""

  function QueueResourcesForLoad( resManager, resTbl, alloc )

  DebugPrint( "Loading: Queuing resources for load." )

  --this if/then block is the modded code, the rest is original

  if swapLevel ~= "" then

  for i,v in ipairs (resTbl) do

  if v.class == "Script" then v.source = "Level_"..swapLevel.."/"..v.name..".lua"

  elseif v.class == "Binary" then v.source = "Scripts/Level_"..swapLevel.."/"..v.name..".lua"

  elseif v.name == "LvlMus" then v.source = swapLevel.."-MUS.bnk"

  elseif v.name == "LvlSfx" then v.source = swapLevel.."-SFX.bnk"

  elseif v.class == "Texture" then v.source = "Level_"..swapLevel.."/DuneColorShadow.dds"

  elseif v.class == "TerrainData" then  

  v.outDir = "Level_"..swapLevel.."/"

  v.srcGround = "Level_"..swapLevel.."/LandColor.dds"

  v.srcHeight = "Level_"..swapLevel.."/Heightmap.dds"

  v.srcMask = "Level_"..swapLevel.."/MaskData.dds"

  end

  end

  swapLevel = ""

  end

  for i,resCons in ipairs( resTbl ) do

  DebugPrint( "Loading: Queuing "..resCons.name..", a "..resCons.class.."." )

  -- Allocate the resource object.

  local metatbl = _G[ resCons.class ]

  local res = metatbl.new( alloc )

  -- Initialize some values in the resource object based on the

  -- construction table.

  resCons.class = nil

  for varName,varValue in pairs( resCons ) do

  local varAccessor = res.__vars[ varName ]

  if varAccessor then varAccessor( res, varValue ) end

  end

  -- Tell the C++ end this resource is ready to be loaded.

  resManager:AddToLoadList( res )

  end

  end

 

"Script" resources are Lua files embedded in Journey.exe, but all other resources are loaded from the game folders.

 

 

Keep in mind that some types of level objects reference each other in a way that will cause the game to crash if something is wrong/missing, so some resources can only be safely replaced if you properly replace certain others as well.

If you try to load a resource that doesn't exist, some resource types will allow it and just use nothing for that resource, but other types will make the game crash.

<nowiki>{  

  class = "ScreamBank",

  name = "LvlSfx",

  source = "Graveyard-SFX.bank"

  class = "ScreamBank",

  name = "LvlMus",

  source = "Graveyard-MUS.bank"

  class = "TerrainData",

  name = "TerrainData",

  outDir = "Level_Graveyard/",

  srcGround = "Level_Graveyard/LandColor.dds",

  srcHeight = "Level_Graveyard/Heightmap.dds",

  srcMask = "Level_Graveyard/MaskData.dds"

  class = "Binary",

  name = "HullInstances",

  source = "Scripts/Level_Graveyard/HullInstances.lua",

  type = "Hull"

  class = "Binary",

  name = "DecorationMeshInstances",

  source = "Scripts/Level_Graveyard/DecorationMeshInstances.lua",

  type = "Decoration"

  class = "Script",

  name = "EnvNodeInstances",

  source = "Level_Graveyard/EnvNodeInstances.lua"

  class = "Script",

  name = "MarkerInstances",

  source = "Level_Graveyard/MarkerInstances.lua"

  class = "Script",

  name = "ParticleEmitterInstances",

  source = "Level_Graveyard/ParticleEmitterInstances.lua"

  class = "Script",

  name = "SoundEmitterInstances",

  source = "Level_Graveyard/SoundEmitterInstances.lua"

  class = "Script",

  name = "SignInstances",

  source = "Level_Graveyard/SignInstances.lua"

  class = "Script",

  name = "SignData",

  source = "Level_Graveyard/SignData.lua"

  class = "Script",

  name = "JetInstances",

  source = "Level_Graveyard/JetInstances.lua"

  class = "Script",

  name = "DynamicNodeInstances",

  source = "Level_Graveyard/DynamicNodeInstances.lua"

  class = "Script",

  name = "CameraKeyFrameInstances",

  source = "Level_Graveyard/CameraKeyFrameInstances.lua"

  class = "Script",

  name = "StartLocation",

  source = "Level_Graveyard/StartLocation.lua"

  class = "Script",

  name = "TimelineInstances",

  source = "Level_Graveyard/TimelineInstances.lua"

  class = "Script",

  name = "TriggerInstances",

  source = "Level_Graveyard/TriggerInstances.lua"

  class = "Script",

  name = "ClumpInstances",

  source = "Level_Graveyard/ClumpInstances.lua"

  class = "Script",

  name = "RailInstances",

  source = "Level_Graveyard/RailInstances.lua"

  class = "Texture",

  gammaRemap = true,

  name = "DuneColorShadow",

  source = "Level_Graveyard/DuneColorShadow.dds"

}</nowiki></div></div>

==Adding/Modifying Individual Level Objects ==

The ''Something''Instances/etc tables that you construct to load level objects into the Names table are usually (but not always) cleared automatically after the functions run, to free up memory.

From tests done by inserting logging code into the level-object-loading functions, this appears to always be the order that level objects get loaded into the Names table, in all levels. You should probably use the same order when adding/modifying different types of level objects at the same time, it is not yet known if doing them in a different order can break anything.

# Environment Nodes

# Markers

# Jets

# Rails

# PrintNameTableSize() from Helpers.lua is called - seems like a safe/good function to edit so it instead adds/modifies all the level objects or other things you want ready before the level actually "starts"; though for level object mods that you want ever since the level starts, it's probably better to just [[Loading Level Objects When Level Starts|insert them directly into the initial object table that gets loaded]]

With this method by itself, if you change the trigger type to a different one than the original, it seems to (sometimes?) not work due to it expecting different data types; it's not yet known how to completely change the trigger type during a level, but it can be done at the start of a level. You might be able to at least change trigger types if the Vars would be the same data types/names - for example if two trigger types both use { var1 = float, var2 = string, var3 = a Clump of Hulls, var4 = boolean } you could possibly switch from one type to the other and change the Var values and it would work; not tested yet.

 

 

With this method alone, new Trigger ObjectNames are apparently added to the Names table for the rest of the level, but the actual data defining what the Trigger should do is '''not''' added to the section of memory where normal Trigger data is stored. Wherever the data is, the Trigger does exist at least until the end of the frame (maybe a few frames) and it can be activated for that short time, but then the data is overwritten and your game will crash if it tries to activate the nonexistent Trigger. Based on other research, the triggers might be permanent if you run the same <code>TriggerInstances = { whatever }</code> code again before you run ResolveTriggerNames, but this hasn't been tested.  

If that doesn't work, one solution to create new "persistent" Triggers might be to have this code running every frame - though you'd have to make it not run while the normal level load/unload stuff is happening. Haven't tested that yet.

==== Spawning instant one-time Triggers ====

If you just want to make a new Trigger that instantly activates and then is removed from memory by Lua garbage collection after it's done doing its stuff ( instead of being a "normal" Trigger that relies on other Triggers to make it happen and can be reused) you can use the SpawnEvent function from PWeb3.lua. It seems that SpawnEvent is not a global function, so you have to re-define it to use it globally.

  <nowiki>SpawnEvent {EventAfterDelay = {delay = 0.01, effects = Names["NewGameStandUpEvents"]}}</nowiki>

  <nowiki>SpawnEvent {EventAfterDelay = {delay = 0.01, effects = Names["e7fa07adac45a2fb9a369edcf5964ec7"]}}</nowiki>

  <nowiki>SpawnEvent {EventAfterDelay = {delay = 0.01, effects = Names["e7fa07adac45a2fb9a369edcf5964ec7"]}}</nowiki>

===Sound Emitters===

Markers are point locations, which objects can be aimed at/away from, moved towards/away from, or attached to by certain Triggers.

Markers can be added and/or modified in a similar way to Triggers and Clumps, based on MarkerInstances.lua's and the functions in Markers.lua:

Rails are invisible lines drawn between a set of point locations, which may be "closed", as in the last point connects back to the first point. They seem to mostly be used as a path for an object/etc to move along, but are also used for other kinds of things that are based on a "2D" line in space - like some wind walls are an infinite flat plane stretching up and/or down from a Rail.

===TBD / Other ===

These are the remaining types of level objects/resources. They can *maybe* be manipulated in real time with Lua code, but it's not yet known if/how it can be done.

==== Hulls====

Hulls are 3D regions of space, which are used as collision geometry and/or a way for Triggers to determine "if ''this thing'' is touching/inside ''this region'', do ''this event''", and also can have some built-in properties like being wind walls, etc.  

You can change the Hulls loaded at start of level by editing HullInstances.lua.bin in the folder for that level under Data/Scripts.

These are LevelSfx''Somewhere''-SFX.bnk and LevelMus''Somewhere''-MUS.bnk in the Data/Sounds folder; not much is known yet about how to edit these at all, other than renaming files to swap one level for another, or editing the code for QueueResourcesForLoad() to change the sound bank resource in the resource table it receives at the start of the level.

====TerrainData====

Many of the functions for creating level objects need a related "somethingBarn"/etc - many of them already have this as "game:somethingBarn()", but some don't appear to have any predefined global variable in Lua. For at least some of these, you can still access it and make your own global variable for it, and then use that variable whenever a function calls for a "somethingBarn". (This has only been tested with Creatures)

     Hack_CreatureBarn = creatureBarn

    --/Mod