LunaDLL Tutorial

Using lunadll.txt scripts
The most important things to think about are the action you want to do and the point at which the action should happen. The scripting engine only deals with those two things: A time, and an action.

Example times:
 * While loading a level
 * Always
 * In section 1
 * In section 2
 * When a timer runs down
 * When touching a block of a certain type
 * When typing a custom cheat code
 * When a condition is met such as NPC with ID 138 no longer exists

Example actions:
 * Change the player character
 * Change the powerup
 * Change the reserve powerup
 * Play a sound
 * Change the music
 * Show text
 * Trigger an event
 * Manipulate game memory somehow

The basics
The first step is creating a file named lunadll.txt in your level folder. That's it.

Structure
There's only 4 things you'll be writing in your lunadll.txt.

Time designator - #
...
 * 1) designates a time of an action. They mostly correspond to sections of the level
 * 2) -1 means during level load
 * 3) 0 means "always"
 * 4) 1 means section 1
 * 5) 2 means section 2
 * 1) 21 means section 21


 * 1) 1000 and up is an advanced feature for designating custom events / custom blocks of commands

Once you write say #-1, then all commands you write from then on will be run during the level load time of your level, until you write #1 or some other designator.

Comments - // comment
Any line that contains a // will be understood as a comment. Comments are only for humans to read, and the scripting engine ignores them. They're actually important for remembering just what the hell your code is supposed to do, and for others to understand what your code does.

Commands - Kill,0,0,0,0,0,0
Commands are the most important part of lunadll scripts, and the most complicated. There's no way to remember them all or what all of the parts of one do usually, so you have to check the reference.

They mostly have the same parts, separated by commas

"Kill" - This first part is the command name. It's the easiest part to remember and explains what the command does, usually. This one kills something. "Infinite flying" activates infinite flying for the player, and so on.

After each command name, there are 6 parameters separated by commas. What each one does is specific to each command, and they're quite hard to remember, which is why you'll have to refer to the reference. But there is some underlying pattern.

First - The target parameter
The first number is usually the "target" of the command. If you want the command to target the player, 0 is usually the player. If you want to target the "key" NPC (the thing you pick up that opens lockd doors), well you need to target the key's NPC ID (the key is NPC ID 38)

Second, Third, Fourth - Options
Parameter 2, 3, 4 are extra parameters that can mean just about anything, but for a lot of commands that aren't complicated, they usually aren't used and are just 0. Check the command reference.

Fifth - Active time
Parameter 5 is virtually always the "active time" specifier. Basically it's how long the command will "run" before finally deleting itself. 0 means it never runs out. 1 means it lasts 1 frame. 60 means it lasts 60 frames (1 second), and so on.

Keep in mind that commands don't run at all unless they're in the section you're in. A command in #21 with 1 frame active time will sit there forever until the player actually gets to section 21, and then it will run once and then die.

Sixth - Text
Unlike the others, the 6th parameter can also be entered as text, but is oftentimes just left as 0 anyway. It's usually where you type messages, decimal numbers, and options.

That's all you need to know about commands.

Script footer - #END

 * 1) END is a special string you should put at the end of your .txt file. It's pretty simple - just put #END after everything else.

Examples
Here's a bunch of examples in ascending level of complexity with lots of comments

Basic filter script
That's the whole thing. First we have the level load designator, which is where you normally want a filter. FilterToBig lowers Demo's powerup down to mushroom level if she has anything higher than a mushroom, and does nothing if she's small.

FilterToBig's 6 parameters do nothing except the 5th, the active time. It's set to 0 which means "always", but since it's in the level load section, it only works for that 1 frame when the level is loading. If this were in section #0, Demo would never be able to get a powerup higher than a mushroom because she would constantly be filtered to bigness.

Basic filter script 2
Same thing as filter 1, except it deletes your mount/yoshi/shoe if you have one.

Basic filter script 3
Let's change things up. The designator is now section 2, and the active time is 180. That means when you enter section 2, the player will constantly have his reserve powerup removed over the span of 3 seconds. Why you would actually do this is another story.

Bad Example
This is a bad example because the command exists in the level load section. This command in particular doesn't work unless it's continuously active, and in the level load section it won't actually do anything. It should be under #0

Multi character filter
This example removes the possibility of Raocow or Princess being in your level. FilterPlayer only has 3 relevent parameters. #2 is the character you want to filter out, and #3 is the character you want it to filter to. 1 is Demo, 2 is Iris, etc. #5 is the active time as usual, but since it's the load level section, any amount is fine.

Fairness (lunadll version 7+)
What might that do? #0 is the always section, and ClearInputString... clears the keyboard input buffer. With an active time of 0, it never stops. The keyboard input buffer is filled with keyboard strokes and used to identify when a cheat code is entered. Clearing it constantly means no one will be able to enter a cheat code.

Full level
This is mainly here to illustrate the syntax of having a bunch of different things in one script (basically there aren't many rules in the way of syntax)

Modify boss life
NPCs in this game don't have health. They have a hit counter. So a mother brain with 9 hits has 1 hit left. A birdo with 1 hit has 2 hits left. A mother brain with -10 hits has 20 hits left. Only NPCs that can normally get hit more than once can have their hit counts manipulated. To find the NPC ID of an NPC, check the graphics folder or a list of NPC IDs. Currently there's no way to specify one single NPC among many that may be in your level. The command runs for every NPC of the type you specify. This goes for all NPC and block commands actually.

Trigger an event (lunadll version 7+)
This will start the event named "MyEvent" (assuming you put such an event in your level). Pretty simple.

Is this working?
DebugPrint is a command that prints some basic info about how the scripts are running. It's useful for figuring out whether lunadll is even working at all. If you see it reporting that thousands of events are being spawned for no good reason, you should probably recheck your script.

Double the player's lives
This is a memory manipulation command, and it's the most complicated thing you're going to find in here. You can skip this part and just not use direct memory manipulation commands and do just fine.

MemAssign performs an operation on a selected memory location in a global variable section. The game remembers all sorts of things in this space. Lives, coins, the state of switches, timers for everything, score, pointers to level names, directory names, state info like whether or not you're in the editor, in battle mode, how many players there are, how many npcs there are...

Unfortunately, there's no way to be sure which memory location contains what information, unless you poke around in a debugger or scan memory. 0x00B2C5AC just happens to be where the lives counter is always located.

If you know the address of something and the format, you can do basic operations on it with MemAssign. The 3rd parameter in 0x00B2C5AC,2,3 is the 3, which is the operation to perform, here being multiply. The 2nd is 2, meaning multiply by 2.


 * 0 = Assign
 * 1 = Add
 * 2 = Subtract
 * 3 = Multiply <<
 * 4 = Divide
 * 5 = XOR

MemAssign,0x00B2C5AC,2,3 means multiply the value at 0x00B2C5AC by 2.

MemAssign,0x00B2C5AC,2,2 would be subtract lives by 2.

MemAssign,0x00B2C5AC,2,1 would be add 2 extra lives.

MemAssign,0x00B2C5AC,2,0 would be set player's lives to 2.

MemAssign,0x00B2C5AC,2,3,0 - The 4th param is 0 since it's unused

MemAssign,0x00B2C5AC,2,3,0,1 - An active time of 1. More would keep multiplying the value by 2 and it would quickly max at 99.

MemAssign,0x00B2C5AC,2,3,0,1,f - Unfortunately memory is not packed evenly. You need to know the size of the data you're trying to manipulate. For lives, it just so happens that they're a decimal / floating point value (which is odd considering lives are one thing you'd always expect to be a whole number). So the last param specifies what kind of data is operated upon. f means floating point / decimal operation.


 * b - 1 byte
 * w - 2 byte (word)
 * dw- 4 byte (double word)
 * f - 4 byte decimal / floating point
 * df- 8 byte decimal / double precision floating point

1 byte memory is rarely used in this game. 2 byte words are used for many things. 4 byte double words aren't used that often and when they are it's usually something you don't WANT to manipulate this way. The decimal types are very often used for spatial positions of things on the game map.

Custom Events
There are many actions you can do with all these commands, but the "time" part the equation will be lacking unless there are more ways to trigger them besides entering sections.

Any commands designated under a section header higher than 999 will be marked as a custom event block.

Cheat a layer
Really it's self explanatory. Just type "go" and the layer command is run. By the way, layer 0 is "default" layer, so 3 is the first custom layer you can make.

There's actually a terrible problem here. The layer command is set to have infinite time. If you type "go" about 15,000 times, your game will start to lag because there are 15,000 commands being run per frame. When you trigger a custom event, it actually means the event is copied into the "always section", so events are like blueprints. The solution is to lower the active time. 1 is fine since the layer doesn't stop.

Player switch (lunadll 7+)
Now it's getting complicated.

OnInput triggers when you press a certain button. Param2 is 1, which is "up". Param3 is also 1, which means it only detects the key press, not holding them down. With this behavior you can simulate the detection of double taps (or more).

In this code, When you push up the first time, another OnInput (event 1000) is activated for 10 frames. This also waits for an up key press. If you successfully double tap, finally, event 1001 is triggered, which switches the character.

Suicide dance (lunadll 7+)
A big button sequence. Just a more contrived version of the last one.

Timer
This is mainly about Timer. Timer is a useful command for automatic repetition or... timing. It activates the custom event specified in its 2nd param whenever it reaches 0. Param 3 specifies whether or not to display the timer at the top right of the screen. Param 4 specifies whether or not the timer should reset itself whenever it reaches 0. 5 is both the frame countdown time and the time it should reset itself to if it's set to reset.

Pushable layer
If you put some wood blocks (Block ID 1) on layer 3, this script will create the illusion that you're pushing them around by running into them from the sides.

DeccelerateLayerX when active slows a layer (towards 0) by the amount in param 6. This simulates something like friction/air resistance.

BlockTrigger triggers custom events when the target interacts with a certain block type from a certain direction.


 * 0 = player triggers the event, 1+ would be NPC IDS
 * 1 = the Block ID
 * 2 = The direction the block should be touched from to trigger. 1=U 2=R 3=D 4=L
 * 1000 = The event to trigger
 * 0 = active time (forever)
 * 0 = unused

Accelerate layer is just the opposite of deccelerate. The second param is the max speed it'll be allowed to accelerate to.

Play custom sound effect when you collect the axe (luna version 7+)
IfNPC triggers an event based on an NPC condition. 178 means the condition is for axe NPCs. 2 means "no longer exists", so it triggers once the axe is gone.

Infinite looping gimmick
Starts the friendly enemy event, which calls the unfriendly enemy event when it ends, which calls the friendly enemy event again when that ends. Loops forever. Check the reference to be sure about NPCMemSet and IfNPC.

Judgement (luna version 7+)
OnGlobalMem is a powerful trigger command that activates events based on whatever memory location you like. It just so happens that 0x00B2C8C4 is an address which contains a two byte value that represents whether or not you've entered a cheat code before. This is the memory that's checked to see if you can save, and it's cleared by the cheat which lets you save again.


 * 0x00B2C8C4 = address
 * 0xFFFF = value to check
 * 0 = "equals" operation. 1 checks "greater than", 2 checks "less than"
 * 1000 = activate #1000 if the check is true
 * 0 = last forever
 * w = check it like a 2 byte value

Remember that either trigger is constantly being activated every frame because the test is either true or untrue, so one ShowText will be copied per frame. The ShowText commands must not have an active time of 0, because then the old ones would never expire while new ones are constantly being added ever frame. You'd end up with thousands of identical showtext commands being spawned and you would lag out really quickly.

Hide layer when player is Raocow or Sheath (luna version 7+)
It's almost the same as OnGlobalMem, but the player doesn't have a fixed memory address, so you use a short offset this time. It just so happens that 0xF0 is the offset to the memory which contains what character you currently are. To find more offsets, check the reference at the end of the document.

First, keep in mind that these are the character IDs
 * 0 = invalid
 * 1 = demo
 * 2 = iris
 * 3 = princess
 * 4 = raocow
 * 5 = sheath


 * 0xF0 = target is player memory offset 0xF0, which contains the character ID
 * 3 = value to test against is 3
 * 1 = operation to perform is "greater than"
 * 1000 = 1000 is the event to trigger if the character ID is greater than 3
 * 0 = active forever
 * w = check the memory like it's a 2 byte word

The same exact thing (luna version 7+)
These both do the exact same thing. InfiniteFlying is just an easier to understand wrapper around the same operation.

Random refill (luna version 7+)
The comments explain it all.

Scroll text up (luna version 7+)
ModParam is a powerful command that can also totally foul everything up beyond imagining. It changes the params of other commands. The challenge is identifying the commands. Param 4 and 6 are used to specify which command you're looking for. Param 4 is which # section the command is in, and Param 6 must match the text exactly of the command you want to modify. Since most commands don't use text you can just write anything in them and then match it later with ModParam.


 * 3 = modify the third param (ShowText's Y coordinate)
 * 1 = amount to modify by
 * 2 = modify by subtracting
 * 0 = look in #0 for the command to modify
 * 0 = modify forever
 * FAREWELL... = the command to modify will have this in the text field

Reference
Most of the structure of the player's data is known actually. You can trigger off of any of it with OnPlayerMem, or change any of it with PlayerMemSet, but a lot of them are useless or not well understood at the moment.

There's less information on the structure of NPC data. You can manipulate NPCs with NPCMemSet.