Development Blog

In fact, I bet it would even be possible to add a connection to SetColor() or another engine function without any script at all on the target entity. At that point it's basically a lambda function that gets executed when the event occurs.

It actually works:

auto model = CreateBox(world)	
model->AddScript(L"Scripts/Objects/test.lua");
auto connection = model->Connect("Update", model, "SetPosition");
connection->AddArgument(1);
connection->AddArgument(0);
connection->AddArgument(10);

Holy **** this is some crazy stuff. The line between visual scripting and inter-object communication has been blown wide open.

model->Connect("Update", model, "self:SetColor(1,0,0,0) self:SetRotation(90,0,0) self.health=9000");

Okay, so from the perspective of Lua, there is no difference between a Lua function like Entity:PickupWeapon() and an engine function like Entity:SetPosition(), nor is there any difference between how entity.position (an engine value) and entity.health (a script value) are treated. Either could be used as an argument in a flowgraph connection. However, outputs are still limited to Lua-defined script functions, unless I want to add a call to FireOutputs(<functionname>) in every single method in the engine (which I don't).

There's no more concept of a "script" object attached to an entity. There's just objects, and they can have extra values. Some of these extra values are functions.

Do you have it so we can connect multiple functions to an "event"?

32 minutes ago, Rick said:

Do you have it so we can connect multiple functions to an "event"?

I don't understand. What is an event? Do you mean this?:
https://www.leadwerks.com/learn?page=API-Reference_Object_EventQueue

I suppose you could do this:

model:Connect("Update", "EmitEvent(EVENT_GAME_BEGIN,model)")

I have read your blog here but I find it extremely confusing.

Nice, I like the concept you are proposing here. Just adding my 2 ct:

 

When you said, there was no remove-function for a script, that makes perfect sense for scripts that are only setting variables, as you mentioned. However, you might want to have the option to remove these functions. Let's consider your tank-example: If you somehow lose your main cannon, you might want to remove the script associated with it, such that future calls to GetTarget() do not call the function of the main cannon anymore.

 

There is another issue with your tank-example: If you have two functions called GetTarget(), you would likely also name the corresponding setter-function SetTarget(), each. However, this would mean that you can only set the target of both at the same time, if you did not name them AISetTarget() and CanonSetTarget(). For this reason, I think, you should draw a line here so you have to make explicit whether you want to call functions from a different script or only those of the same script. I would suggest, you do the following:

• SetTarget() will only execute the function from the current script. If there is no function named SetTarget in the current script, an error should be thrown
• All::SetTarget() (or something similar) will execute functions from all attached scripts (as well, as the current script) with the current name (i.e. the way you proposed)
• FILENAME::SetTarget() will only execute the function from the script called FILENAME. If this script does not exist or it does not have this function, an error should be thrown

So for each function you define in your script, you would need to internally create three different mappings. Doing this would give everyone maximal flexibility while at the same time preventing some unforeseen errors. So, everyone could still use their isolated scripts the way they used them before without even needing to change anything. If you want to call functions from other scripts, you have the choice to select either only one specific other script or all others

 

4 hours ago, Josh said:

model:Connect("Update", "EmitEvent(EVENT_GAME_BEGIN,model)")

Update is the "event". In all the stuff you're saying you are linking functions to "events". Then when that "event" is fired/called it's actually calling the function we assigned to it. Being able to assign multiple functions would be nice. In your example your 2nd param is basically a script in itself as it's getting executed, but before you were assigning things to straight functions to be called and so I was wondering if you could assign to multiple functions and when Update is called it'll loop through and make the call to all functions attached.

If you changed the name of Update to onUpdate then it becomes clearer that it's basically an event that the engine is raising every frame. There are other events like onCollision. Same idea. You're simply allowing users to have their functions called when these events are raised (when those engine functions are called).

That's the premise of my blog post. Raising and event is just like calling a function, except the event can have N number of functions that the user assigned to be called when the event was raised. It allows one to make events when they don't know what a user wants to do with said event. It gives them the flexibility to do whatever they want when an event is raised.

It's easier to think about a GUI button. When it's pressed the UI library "should" raise and event and the user would have attached a function (or more than 1) to that event that gets called. This is opposed to the polling that you use in your GUI system. So you either poll or use events.

There's no limit on the number of outgoing connections you can create.

This will call the Foo() function attached to the target entity, if it is present. Foo() can a function from a script or an engine function:

model:Connect("Collision", target, "Foo")

This will call the global Foo() function:

model:Connect("Collision", "Foo")

This will execute the passed code, and the target entity will be available in the "self" variable. In this case, the target entity doesn't even need to have a script at all:

model:Connect("Collision", target, "self:SetColor(1,2,3) self:SetPosition(3,3,3)")

This will execute the contained code:

model:Connect("Collision", "print(545)")

Multiple connections from one function are fine:

model:Connect("Collision", target, "Foo")
model:Connect("Collision", target2, "Foo")
model:Connect("Collision", target3, "Foo")

The Connect command returns a Connection object. You can add arguments to be passed to functions from other object functions:

local connection = model:Connect("Collision", target, "Foo")
connection:AddArg(button,"GetState")

Or you can use a member:

local connection = model:Connect("Collision", target, "Foo")
connection:AddArg(button,"state")

Or you can use a literal value with no object:

local connection = model:Connect("Collision", target, "Foo")
connection:AddArg(3)

Of course this is all meant to be used to in the visual editor. I don't expect people to code these things directly, but it's there if you want it, and it is the foundation of what's actually happening when you use the flowgraph system. How well does that fit with your ideas of what you want to do?

So :Connect() is an entity function. Can we have our own event? In the example above "Collision" can be thought of as an event. When it's called/raised you call the connected functions. Can we have our own lua defined event that we can call and it'll call all the connected functions? 

-- treating this more as an event that I can call and it'll in turn raise all the connected functions
function Script:MyScriptsEvent()
end

self:Connect("MyScriptsEvent", target, "Foo")

So when inside self I "raise" or call MyScriptsEvent function it'll call Foo() from target?

Why do you do the AddArg()? Is that for the C++ side of things? Lua can do variable number of arguments so you could capture all arguments after the 3rd one and pack them off in a table and then unpack them when you make the call and they'll fall in the right order.

 

22 minutes ago, Rick said:

So :Connect() is an entity function. Can we have our own event? In the example above "Collision" can be thought of as an event. When it's called/raised you call the connected functions. Can we have our own lua defined event that we can call and it'll call all the connected functions? 

-- treating this more as an event that I can call and it'll in turn raise all the connected functions
function Script:MyScriptsEvent()
end

self:Connect("MyScriptsEvent", target, "Foo")

So when inside self I "raise" or call MyScriptsEvent function it'll call Foo() from target?

Why do you do the AddArg()? Is that for the C++ side of things? Lua can do variable number of arguments so you could capture all arguments after the 3rd one and pack them off in a table and then unpack them when you make the call and they'll fall in the right order.

 

I am writing this in C++, so that is the reason for the AddArgs thing, but it is something I am still thinking about.

You could create a connection with a made-up name, and then call entity:Fire("myevent") but why would you do that when it is just as easy to call the code you want to call?

local connection = self:Connect("MyEvent",self.material,"SetColor",1,0,0)
connection:Fire("MyEvent")

This seems more straightforward to me:

self.material:SetColor(1,0,0)

 

1 minute ago, Josh said:

You could create a connection with a made-up name, and then call entity:Fire("myevent") but why would you do that when it is just as easy to call the code you want to call?

You do that for the reason my blog post talks about. When making reusable scripts for others to use, you create events for things that happen inside that script. Users connect whatever they want to that scripts events (I wouldn't know what they want to do at the time of writing my reusable script) and when I fire them inside my reusable script their custom code is called. 

If a health script wanted to tell the outside world when the health dropped below 50% then inside it's Hurt() function when health is < 50% is would raise or call an event. Since these are functions in  your example it can just call the function onHealthBelowFiftyPercent()  I guess but internally that function would be empty and only exists for others to connect to it so they can call their functions. So in that regard it acts more like an event since it's sole purpose is for others to just connect to it and it's body is empty.

Just to put a more concrete example with this. Let's say the goal is to have a heartbeat sound play when health is < 25% and to also add pulsing red post process effect around the edges of the screen. A reusable way to do something like this so that others can modify it to their needs would be to:

1. Create a Noise.lua script. This would have a property of what sound to play and a function Play() (some other properties as well).
2. Create a HurtPostProcessing.lua script. It will do the pulsating red boarder when you call it's TurnOn() function and you can turn it off by calling it's TurnOff(). It can have properties as well to control certain aspects like how fast the pulsating is.
3. Create a Health.lua script that has a Hurt() function and an onHealthBelowTwentyFivePercent event. It also has properties like max health and such.

 

All 3 of these scripts are separate and were created by 3 different people and put in the shop. I come along and add all 3 scripts to my player entity. I set the noise.lua wav file property to some heavy breathing sound and I connect it's Play() function to the Health scripts onHealthBelowTwentyFivePercent. I do the same for the HurtPostProcessing script. I now have 3 scripts that knew nothing about each other working together help me reach my goal effect. This is the benefit of "events" and event programming.

If we used the polling and shared variable way of doing things this wouldn't be ideal. My reusable Noise script should never know or care about a Health script. Inside it's Update() method it shouldn't be checking if self.health is < 25% because self.health has nothing to do with Noises. It couldn't possible know all the use cases for playing noises. The main benefit of attaching multiple scripts is the reusability and cleanliness of code. Put a nice user interface on top of hooking all this up and you have a very friendly system to make complex functionality without much coding by the user. This gives the coders a framework to create reusable scripts, and down the line a revenue stream by selling those scripts.

if you want to create a function that will not be sharing variables with other functions with the same name, are you thinking of having a using namespace convention?

Just now, Gonan said:

if you want to create a function that will not be sharing variables with other functions with the same name, are you thinking of having a using namespace convention?

You can prefix your variables with a unique string or add them into a table:

function Entity:Start()
  self.scriptname_value=100
end

Or:

function Entity:Start()
  self.scriptname = {}
  self.scriptname.value=100
end

 

@Rick That's a good example.

Let's say this is our health script (or an AI script with a health value in it):

function Entity:Start()
    self.health=100
end

function Entity:Hurt(damage)
    self.health = self.health - damage
end

function Entity:Reset()
    self.health = 100
end

And here is our sound script:

function Entity:Start()
    self.sound_heartbeat=LoadSound("Sound/heartbeat.wav")
    self.source = self:EmitSound(self.sound_heartbeat)
    self.source:Pause()
end

function Entity:Hurt(damage)
    if self.health < 25 and self.health > 0 then
        self.source:Resume()
    else
        self.source:Pause()
    end
end

function Entity:Reset()
    self.source:Pause()
end

And our overlay script:

function Entity:Start()
    self.shader_pain=LoadSound("Shaders/PostProcess/pain.shader")
end

function Entity:Hurt(damage)
    if self.health < 25 and self.health > 0 then
        if self.camera ~= nil then self.camera:AddEffect(self.shader_pain) end
    else
        if self.camera ~= nil then self.camera:RemoveEffect(self.shader_pain) end
    end
end

function Entity:Reset()
    if self.camera ~= nil then self.camera:RemoveEffect(self.shader_pain) end
end

So these all need to recognize that Hurt and Reset are common functions, and two different scripts use 25 as the threshold for the pain state. No flowgraph connection is required.

Another way would be to have the health script control the pain state:

function Entity:Start()
    self.health=100
end

function Entity:StartThePain()
end

function Entity:StopThePain()
end

function Entity:Hurt(damage)
    self.health = self.health - damage
    if self.health < 25 then
    	self:StartThePain()
    else
    	self:StopThePain()
    end
end

function Entity:Reset()
    self.health = 100
    self:StopThePain()
end

And then the other scripts would use StartThePain() and StopThePain() instead of adding another Hurt() function. Something like this is probably better because it sets a single threshold value inside the health script, so the sound and overlay scripts don't get out of sync.

Another option might be to add a getter / setter type of function that watches a variable. In this case we will use one called ithurts to store the pain stete:

function Entity:Start()
    self.health=100
    self.ithurts=false
end

function Entity:Hurt(damage)
    self.health = self.health - damage
    if self.health < 25 then self.ithurts = true else self.ithurts=false end
end

function Entity:Reset()
    self.health = 100
    self.ithurts = false
end

And your sound script would look like this:

function Entity:Start()
    self.sound_heartbeat=LoadSound("Sound/heartbeat.wav")
    self.source = self:EmitSound(self.sound_heartbeat)
    self.source:Pause()
end

function Entity:set_ithurts(value)
    if value then
        self.source:Resume()
    else
        self.source:Pause()
    end
end

What are your thoughts on this?

You would never have/want health information inside a sound script. That script has stopped being generic enough for reuse at that point and it's now very "leaky". Other responsibility is leaking into that script. If you want 3 instances of that script all playing sound on different events you either bloat the 1 script to handle all use cases (which no reuseable script will know all possible use cases) or you create 3 different scripts. Both are bad options.

There are all sorts of different events that you want to play a sound and trying to build in common functions or sharing information directly inside another script is just a mess waiting to happen and again kills reuse.

Being able to link the event to a function in the editor is the way to go. Those other ways you're showing can't really be done via the editor unless you start doing code generation inside the scripts themselves which leads to a whole other mess.

 

I think your StartThePain()/StopThePain() is the right idea as long as the idea is that I can connect (in another script or via editor) my sound scripts Play() and Stop() function to those functions (events). That way the 2 scripts are unaware of each other on the inside of themselves. The sound script has no knowledge internally of the health script and vice versa. A much cleaner and reusable situation.

 

In that case, what you probably want is a per-entity flowgraph that can simply call engine commands. Does that sound right? I mean, why would you need a whole script for something that is just one command to play a sound?

Because that script has properties like the current noise does. So you need a way to capture those and combine it with the functionality. The noise script can emit events as well like onFinishedPlaying, onHalfWayThrough whatever. A script is just a class to hold all that information, then you make instances of it by attaching it to entities.

It's not engine commands. We have our own scripts that do a lot of gameplay specific events and functions that we would want to hook up as well. OnScorePoint, OnFoundTreasure, etc etc. Stuff that you can't make common commands for but are useful for our games scripts.

Now, once you've attached a bunch of scripts to an entity then yes you need a place to connect everything between those scripts and a per entity flowgraph is a good idea on how to do that actually. One could do another script that is specific to that entity and do it all by typing the code if they wanted to do that but a flowgraph for each entity would be a really cool way to do that. If you could save the entity as a prefab and it has all that information (scripts, flowgraph, model, etc) that would be cool too!

Here's a concept of a diagram that would generate a script that would do this.

I'm not following why you want to programmatically generate a script to do this specific game requirement. With the idea of connecting functions to 'events' that's just configuration information between generic/reusable user created scripts that is ran when the starting 'event' is triggered.

If you're thinking about a per-entity flowgraph, all you need is the information of the entity, attached scripts, and the connecting information. After all that is loaded, read a text file that stores the config of what hooks to what and since lua is so flexible that string information in the text file should be able to be setup since everything in lua can be accessed with it's string name.

So let's imagine entity1 has a health script, sound script, postprocessing script attached to it. The per entity flowgraph could just be a text file config file I would think. When saving you're saving the 'event' variable name and what script it belongs to and the called function and what script that belongs to. All that information can be stored as a string and read back as a string and then you can get all the actual lua objects from their string names. So not following the idea of generating a script to do this functionality.

Because a lot of people want to choose from a list of options and create things visually, then see the code that generates.

Lua user base is 10x bigger than C++ user base. I think a non-coding userbase would be 10x bigger than Lua userbase.

That's why I'm confused as to why you said generated script. No lua script needs to be generated for visual coding really. That's all just configuration of what hooks to what. Code generation adds another layer into the mix.

The above flowchart would generate this code:

function Object:Start()
    self.source = self:EmitSound(LoadSound("Sound/ouch.wav"),50)
end

function Object:Update()
    if type(self.health)=="number" then
        if self.health < 25 then
            self.source:Resume()
        else
            self.source:Pause()
        end
    end
end