Difference between revisions of "Loading Level Resources With Lua"

[[Category:Level Resources]]

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

==Loading Resource Files==

For example, if you inject this script, 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''.

  swapLevel = ""

   

  end

  end

"Script" resources are .lua's embedded in Journey.exe, but all other resources are loaded from the game folders.

Here is the format of resTbl as it gets passed to QueueResourcesForLoad:

  {  

  {

  }  

  }

==Adding/Modifying Individual Resources==

'''Important things to remember'''

#Environment Nodes (apparently gets loaded twice)

*Load order not yet known for Particle Emitters, Sound Emitters, Terrain Data, the SFX/Music Banks, or the DuneColorShadow texture.

===Triggers===

Triggers are various types of events, including events that activate other events. They control basically everything that ever "happens" in a level, apart from basic player actions.

The functions in this category are mainly from EventSetter.lua .

====Modifying Triggers====

To modify existing Triggers, find them in TriggerInstances.lua, define them in the TriggerInstances table with the same format used in that lua, then run the ResolveTriggerNames function.

Code "template":

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. 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.

====Creating new Triggers====

You can temporarily create new triggers basically the same way, by adding the CreateTriggers function:

<code>

TriggerInstances = { ObjectType = "TriggerInstances", { ObjectName = "NewTrigger", GardenerName = "NewTrigger_G(this name doesn't matter?)", Type = "whatever type you want", Shortcut = "", Vars = { whatever vars that type of trigger uses } }, {same for more new triggers} }

CreateTriggers( game:eventBarn() )

ResolveTriggerNames( game:eventBarn(), game:clumpBarn() )

</code>

<code>

TriggerInstances = { ObjectType = "TriggerInstances", { ObjectName = "TextTrigger", GardenerName = "TextTrigger_G", Type = "DisplayText", Shortcut = "", Vars = {text = "Check this out, I can do a backflip", x = 0, y = 0, duration = 3, fadeTime = 0.5 } }, { ObjectName = "AnimTrigger", GardenerName = "AnimTrigger_G", Type = "PlayDudeAnim", Shortcut = "", Vars = { animName = "HitBodyMAir", clearAnimQueue = true, useLocal = true} } }

CreateTriggers( game:eventBarn() )

ActivateTriggerByName( "TextTrigger" )

ActivateTriggerByName( "AnimTrigger" )

</code>

It is not yet known how to make the actual Trigger persist for the entire level. Until we figure that out, 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.

Once you have created a new Trigger, you only need to use ResolveTriggerNames() to re-create it after its data is deleted. However, there does not appear to be any harm in using CreateTriggers() for it again, it just won't do anything - the Names table will stay the same.

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

If you just want to make a new Trigger-like event that instantly happens and then disappears ( 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.

SpawnEvent { TriggerType = { var1 = x, var2 = y, var3 = z... basically the same kind of Vars table that would be used with that Trigger type }

</code>

===Clumps===

Clumps are groups of multiple objects, used so that a single Trigger can reference and/or manipulate everything in the Clump at once.

All Objects in a clump might need to be the same type of object, like they must be all Triggers, or all Hulls, or all Meshes, etc - not tested yet.

The functions in this category are from ClumpLoader.lua.

====Creating new Clumps====

To create new Clumps, define the ClumpInstances table with the same format used in ClumpInstances.lua (but concatenated, not with line breaks). Then run the LoadClumps function, then the SetClumpMembers function.

Code "template":

<code>

LoadClumps( game:clumpBarn() )

SetClumpMembers( game:clumpBarn() )

</code>

<code>

LoadClumps( game:clumpBarn() )

SetClumpMembers( game:clumpBarn() )

</code>

<code>

SpawnEvent {EventAfterDelay = {delay = 0.01, effects = Names["NewGameStandUpEvents"]}}

Demonstration of the Clump it's duplicating:

SpawnEvent {EventAfterDelay = {delay = 0.01, effects = Names["e7fa07adac45a2fb9a369edcf5964ec7"]}}

</code>

====Modifying Clumps====

To modify existing Clumps, get them from ClumpInstances.lua and do basically the same code, but without the LoadClumps function:

<code>

SetClumpMembers( game:clumpBarn() )

SpawnEvent {EventAfterDelay = {delay = 0.01, effects = Names["e7fa07adac45a2fb9a369edcf5964ec7"]}}

</code>

===Timelines===

Timelines are timed sequences of Trigger activations, used to organize cutscenes and other events where a bunch of Triggers get activated in a row.  

LoadTimelines( game:timelineBarn() )

</code>

===Creatures / Dynamic Nodes===

Creatures include Fish/Carpets, Guardians/War Machines, Cloth Guardians/Whales/Dragons, Jellyfish, Flow creatures, and Meteors/Comets/Shooting Stars.

<code>

DynamicNodeInstances = { construct based on the format in DynamicNodeInstances.lua }

CreateCreatures( game:creatureBarn() ) --only used when adding new creatures(?)

ResolveCreatureNames( game:creatureBarn() )

</code>

It seems that Creatures/Dynamic Nodes might actually be Triggers, based on how TriggerInitialize() is also used in Creatures.lua - so new Creatures might have the same issue as Triggers, and might disappear from the Names table shortly after being created with this method.

===Particle Emitters===

Particle Emitters emit particles (sparkles, puffs of sand/dust, etc.)

ParticleEmitterInstances = { construct based on the format in ParticleEmitterInstances.lua }

</code>

Based on tests where logging code was put in LoadEnvFXParticles() and ParticleEmitterInitialize() and nothing was logged, it seems this script doesn't actually run at level start, so Particle Emitters might be added to Names table by another Lua script or by inaccessible C code. But maybe this function could still add/modify Particle Emitters anyway.

===Sound Emitters===

Sound Emitters emit sounds. They can be stationary or attached to a moving object somehow. It seems that most looping music is played by Sound Emitters that are set to be audible at the same volume anywhere in the level.

Based on tests where logging code was put in LoadSoundEmitters() and SoundEmitterInitialize() and nothing was logged, it seems this script doesn't actually run at level start, so Sound Emitters might be added to Names table by another Lua script or by inaccessible C code. But maybe this function could still add/modify Sound Emitters anyway.

===Environment Nodes===

Environment/Env Nodes set the environmental effects within certain regions, such as lighting, sky color, shadows, fog, bloom, etc.

It has not yet been tested, but Env Nodes can probably be added and/or modified in a similar way to Triggers and Clumps, based on EnvNodeInstances.lua's and the functions in Environment.lua:

EnvNodeInstances = { construct based on the format in EnvNodeInstances.lua }

</code>

LoadEnvNodes does ''not'' clear the EnvNodeInstances table automatically upon completion, and the code comments say this causes a crash, so might be a bad idea to do it yourself.

===Markers===

Markers seem to be locations, or regions of space around locations, which objects can be aimed or moved towards/away from by certain Triggers. Also, Markers can be moved around or attached to moving objects by Triggers.

LoadMarkers( game:markerBarn() )

</code>

===Rails===

Rails seem to be paths that objects can move along.

</code>

( There doesn't seem to be a game:railBarn(), so maybe it's a different name in game:, or maybe it's used like RailBarn, RailBarn() or RailBarn(game). )

===Camera Key Frames===

Camera Key Frames seem to be the data for basically any location/angle/etc that the camera can get moved to, whenever the camera moves by itself - not just following behind the player, or being moved around by the player.

LoadCameraKeyFrames( game:cameraSystem() )

</code>

===Jets===

Jets seem to be the physics effect that pushes your avatar down when you are inside certain sandfalls, and maybe other effects. Could probably be used to push the avatar in other directions as well.

</code>

( There doesn't seem to be a game:jetBarn(), so maybe it's a different name in game:, or maybe it's used like JetBarn, JetBarn() or JetBarn(game). )

===Signs===

Signs are scrolling text, used only in the credits. Could maybe be used for other scrolling text as well, although there seem to already be scrolling text Triggers that might be easier for that.

<code>

Credits = { construct based on the format in SignData.lua }

SignInstances = { construct based on the format in SignInstances.lua }

InitializeSignBarn( signBarn, signData, signInstances )

</code>

( There doesn't seem to be a game:signBarn(), so maybe it's a different name in game:, or maybe it's used like SignBarn, SignBarn() or SignBarn(game). Also, signData/signInstances don't seem to actually be referenced inside InitializeSignBarn, so they might not be required, but if required then maybe signData is Credits and signInstances is SignInstances. )

===TBD / Other===

These are the remaining types of level 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 are regions of space that never move(?), which are used as physical collision geometry and/or a way for Triggers to determine "if ''this thing'' is touching/inside ''this region'', do ''this event''".

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

====Decoration Meshes====

Decoration Meshes are any visible object other than terrain, fog, particle effects, Strands(?), and the basic "naked" player avatar. By themselves, they are not physical objects, their collision data comes from physical Hulls put in the same place.

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

====Sound Banks====

SFX Banks contain sounds, and references/mixing data for longer sounds streamed from the audio files in Data/Sounds/Streams.

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.

====TerrainData====

Terrain Data determines the terrain's Height Map and Land Color (the color of sand/snow added to the sides and/or top of some Decoration Meshes, and that collects on the player avatars). It also determines Mask Data which seems to be unused.

You can change what is loaded at start of level by editing the TerrainData.bin inside TerrainData.bin.gz in the Data/Terrain/Level_''Somewhere'' folder.  

====DuneColorShadow====

DuneColorShadow is a texture that determines the color of the terrain in a level, and which areas are in shadow.  

You can change what is loaded at the start of a level by editing/replacing the DuneColorShadow.dds texture inside the DuneColorShadow.dds.D3D11x64 file in the Data/Textures/Level_''Somewhere''/Bin folder.