Rick's Blog

Very cool stuff Rick and Roland. I would also love to see more enthusiasm on such a communication framework. I think adding a basic diagram on the flow of the message and the structures it passes through will aid in explaining what you are doing. For instance a character with a health component.

 

1 hour ago, AggrorJorn said:

Very cool stuff Rick and Roland. I would also love to see more enthusiasm on such a communication framework. I think adding a basic diagram on the flow of the message and the structures it passed through, for instance a character with a health component, would aid in explaining how your solution works.

 

I can make one. Give me some hours

An FPS player that can pick health items and have a health meter 

So here is a small example of a game with a first person player with a camera. You can move the player forwards, backwards and turn him around. The camera will detect any items in front of the cursor within a limited range. If you left click on such an item when its detected it will go away, add health to the player and update a health meter showing current health.

Here is a screenshot of the example (here with two different kinds of items to pick and two meters, but besides that its the same)

Instead of diving into coding the player with all its operations to handle we won't in fact make any player coding. Instead we will divide things into components with their own responsibilities. The components is hold together by a runtime object created by LCS and is nothing you don't need to care about. So what is a component then. Its a LUA class that has Events and Actions and is completely isolated and independent of other components. This means it can easily be replaced with another component that behaves in another way. It can also without any changes be used in other projects.

So how would we go about this then. First of all we have some entity's in our scene.

• Health items to pick up (the boxes)
• Player (a simple invisible cylinder) including a FPS camera
• HealthMeter ( GUI showing current health)

Normally we the would have started making Scripts for those items above. But were not this time In fact none of the Entities in the scene will have a Script. Instead we are going to write Component scripts that can be used here or in some other game.

So what components could our player need then? That's up you depending on how you want to design things. Here is a suggested approach by me.

• Input component that handles user input
• Controller component that handles movement of the player and camera
• Health component that keeps track of current health
• Cam component which is the FPS camera

Further on the Health item needs a HealthItem component that reacts to a pickup and a HealtMeter component that serve as a GUI for current health. You don't need to write any Script code for the Entities in the Scene, only component needs some action by you. Each entity will be connected to a GameObject (which is generated in runtime and does not need any coding). This GameObject ties the components together and handles all things to get the communication going. The system is defined by supplying a setup written in JSON format. However you wont need to do that either as I'm currently working on a design application for setting things up and that will be available when we release the system.

Anyway.. so now when we know what components we need, its time to think a bit on what they should to and how they will interact with the surroundings. So lets get started. I won't go through every component but I think you get the idea

Input

Should handle input from the user and generate events accordingly. An event can be subscribed to by any other component and sends some information about the event that happened. All events starts with 'on'. A subscriber of an event must have an action that will be triggered by the event. All actions starts with 'do'.

Events

• onForward is sent when user presses 'W'
• onBackward is sent when user presses 'S'
• onClick is sent when user clicks left mouse button

Controller

The controller is responsible for moving the player

Events

• onMove is sent when the player moves (contains information about current position)

Actions

• doMoveForward moves the player forward
• doMoveBackward moves the player backward
• doTurn turns the player around its Y-axis (needs an angle)

Cam

Is simply the camera which is rotated by moving the mouse.

Events

onPick is sent if the doClick action is called when an pickable entity is in front of the camera. The entity is sent with the event.

onTurn is sent when the user rotates the camera by moving the mouse

Actions

doMove moves the camera to a given position

Here is a drawing showing our system now. The yellow parts are entities in the scene (map), the red ones are GameObjects created in runtime holding the components and finally the blue ones are the components which we have to write code for.

L

 Lets have a look at the code for one of our components to see what it looks like

The Controller class must have following functions to be treated as a controller by the LCS system

• init called by LCS to create the controller
• attach called by LCS when its attached to its entity and GameObject

Besides those two, a component can (optionally) have following functions called in the same way as in normal Scripts. If one or more of those exist they are called automatically. 

• update called on UpdateWorld
• updatePhysics called on UpdatePhysics
• draw called on Draw
• drawEach called on DrawEach
• postRender called on PostRender
• detach called on Detach

In the init function you can see how an Event is created. That is all needed to create an Event. 

self.onMove = EventManager:create()

If you then look in the update function you can see how the event is sent by calling 'raise'

self.onMove:raise({Pos=newpos})

This event a contains a position. All event information are sent as tables. In this case a table member Pos set to the current position.

Further there are some actions that can respond to events from outside world. Lets look at one of the actions 

function Controller:doMoveForward()
	self.move = self.moveSpeed 
end

The action is just a normal function that may or may not have an argument. It does not need to return anything. One exiting thing is that all Actions are automatically executed as coroutines which has really cool advantages. I wont go into that here but I thought its worth mentioning.

Here is a code snippet from the Cam component showing an action that can handle an onMove event that has an argument.

function Cam:doMove(args)
	self.camera:SetPosition(args.Pos,true)
end

The args is the table sent with the event ( remember self.onMove:raise( {Pos=newpos} ) ). The args table will contain the member given when the event was raised.

Okay. Lets see how all this works then

In the diagram above you can see the components and the events in action.

1. User presses W and Input:onForward event is sent to the Controller:doMoveForward action which make the player move forward
    
2. The Controller raises the onMove event which is received  by the Cam:DoMove action which moves the camera
    
3. User presses S and Input:onBackward event is sent to the Controller:doMoveBackward action which make the player move forward
    
4. The Controller raises the onMove event which is received  by the Cam:DoMove action which moves the camera
    
5. User moves mouse left and the Cam:onTurn event is raised giving the angle of rotation the movement caused. This event is caught by the Controller:doTurn action which rotates the player in the same angle
    
6. User left clicks the mouse which raises the onClick event which is caught by the Cam:doClick action. If the camera now has an item directly in focus it raises an onPick event which then is caught by the entity's component HealtItem:doPicked.
    
7. In doPicked the HealthItem will hide it self and send a message back to the player telling that it needs to 'add.health' among with the amount of health.
    
8. The message will end up in the Health component (by magic ) and the health will be increased. 
    
9. As the health has changed the Health:onHealthChange event will be raised and is caught by the HealthMeter:doSetHealth action which will show the new health 

The communication between Events and Actions is set as hookups. A hookup means that a component subscribes to an Event. Take our onMove/doMove example above. Setting up a hookup for this is simple

self.Controller.onMove:subscribe( self.Cam, self.Cam.doMove )

But that's done for you by the LCS system in the runtime GameComponent holding the Components for the player. How, you may wonder? This is done by creating a LCS project file (in JSON format) defining the GameObjects, Components and Hookups.

Going into this in detail goes a bit out of scope for this 'short' description, but I can show a cut from that file

{
	"source": "Controller",
	"source_event": "Move",
	"destination": "Cam",
	"destination_action": "Move",
	"arguments": "",
	"filter": "",
	"post": ""
}

This creates the hookup between the Controller and the Cam. This is only a simple example but you can add functions right here also for adding more arguments, making event filters and more.

Code creation. One nice feature is when adding a new component by defining it in the LCS project file, LCS will create the LUA file for the component with everything added. The only thing you will need is to add some code inside the Action functions.

As a last thing I will show how easy it is to take advantage of the actions which are coroutines (by magic). Here is how I raise the health level in the HealthMeter to be smooth

function HealthMeter:doSetHealth(args)

	local value = 1
	if args.Health < self.health then value = -1 end
	
	local goal = Math:Round(Math:Clamp(args.Health, 0, self.max) * self.valueSize)
	while self.pixelValue ~= goal do
		self.pixelValue = self.pixelValue  + value
		coroutine.yield() -- give system some time
	end
	self.power = args.Health
	-- done!
end

 

Hope this have given you some more insight into the LCS system.

PS: Some details has been left out here to increase readability 

Thanks for the extended explanation Roland. I will have to sit down for this and give it a thorough read. Really cool to see how you guys are creating this framework.

I'm going away for a roadtrip tomorrow and won't be back for three weeks. First thing when I'm back is to finish the LCS design editor and then start making some docs and tutorials. After that we will need some beta testers (you have already showed an interest in that). Anyone else is welcome. Will probably be in end of August if God and Thor is on our side. All this will be free when released.

I'd be interested too!

 

21 minutes ago, mdgunn said:

I'd be interested too!

 

Great. All you who are interested just tell here 

We have a long term goal of allowing, from the editor, pulling down and publishing from/to github components that people create for this system. GitHub has a web API and if people use a certain tag on thier components on there we can easily query those and display them in a list to pick from. Sort of like a package manager. However, getting multiple people to use the system will help better define it before we do that. At that point we would want to have everything solid for a version 1 release.

We think that it's really easy to create actions and events and then visually hook those up together to make more complex functionality. 

I sat down last evening to give it a thorough read and I am really impressed. I also love the component editor system. This saves a lot of manual typing to register all components.

What I like the most is that this completely overhauls my default thinking process about the game entities. The losely coupled structure is perfect and I think that this is the biggest downside to most of the code that I currently write. Everything needs a reference to objects in the scene or other scripts. This just makes management so much more easy. 

@Rick That API/components collections sounds awesome. I can allready see dozens of tiny components that can be useful for this. Any ETA on the project beta? nvm, end of august.

I'll give a real world example that can help people get in the event action component mindset.

Tjheldna and I are making an rpg turned based fighting game. Think old school final fantasy like. So you have your characters and enemy characters. When it's one of your characters turn you select an ability and then select a target to do that ability on. Ultimately a message is sent to that entity to do damage to it. I call that message "do.damage". The target entity gets onReceivedMessage event raised whenever it gets a message. We then hook up components actions we want to do functionality to this entities onReceiveMessage.

So in my example case I'm getting a "do.damage" message. So my thought process was I need health in order to take damage so I create a health component. It's a pretty basic component to start with. Simply has a health variable, and an action I named doReduceHealth(args). The arguments table that came along with the "do.damage" message has a 'value' variable with the amount of damage to be done. So inside doReduceHealth() action I reduce my health variable by args.value. I then add the health component to my character entity and hook up its doReduceHealth() action to the entities onReceiveMessage event and part of that subscription I have a filter function that returns true when the args.Message == "do.damage" so that when onReceiveMessage is raised it'll only call my health components doReduceHealth() action when the message we received is "do.damage".  Now my health is being reduced!

So we were rocking that for some time and all going well. The next part shows the lego like idea of this system. It's very much like snapping legos together ifeach lego was a piece of functionality. Because this is an rpg we need stats like armor, strength, etc. In our specific case one enemy has an aura that reduces all damage by 50%. So another stat would be damage reduction. So I know I need these stats thst kind of all play together in some way. So I create a Stat component. Inside I create a variable named damgeReduction which holds a percent value. The point of this component at this point in time is to reduce the damage trying to be done to me. So I create an action named doReduceDamage(args). One good side effect to our system is that actions are called in the order they were hooked up to the event. So clearly I need to reduce the damage coming into use from the "do.damage" event our entity gets before the health component does the damage to our health. So before the health event hookup of the "do.damage" message event I hook up this stats doReduceDamage() action. The other benefit to this system is that arguments to actions is a table and tables are passed by reference. Which means if I modify a variable value that is part of thst table in one component action, the other component actions thst get called after that will see those changes. Perfect! Since our stats doReduceDamage action is called first I'll reduce the args.value number by whatever our stats damageReduction variable is. Now when the health components doReduceHealth action is called the args.value variable is lower. I just easily and in an isolated way snapped on functionality.

The last day or so I've made posts trying to figure out how to draw to a texture and then put that texture on a sprite. The reason I'm doing this is because I need to show the player how much damage was done. I needed the value of the damage being done to show up on screen above the characters head and then rise up a little over time. So guess what? New component! I created a RiseText component. It has an action named doRise(args). I hooked this up to the entities onReceiveMessage event and raise it when it gets the "do.damage" message but it's hooked up AFTER the stats actions so that args.value is already modified and the true value that is being done to that entity's health component. This is where the benefit of coroutines come in. doRise() action of this component does everything right inside itself. It creates the needed variables for buffer, material, etc. draws the text and then loops and tweens the text upward while yielding out. It's nice and more natural to be able to do that all in that one actionvs having to set state variables and do it in that components update() function. An added benefit to why it's nice is because when an action is raised a unique coroutine is created that wraps it. This means that even if the same action is called multiple times each one is ran in its own contained state. So one instance of that action might not be finished while another is called again but because they are wrapped in thier own unique coroutine they don't effect each other. If we didn't have this then calling the doRise() while another rising text was still happening in its update() function would cause thst one to stop so it can do the new request of rising text. If we didn't want that then we'd have to get into possibly storing multiple instances of possible rising text ourself. What a pain. With actions being wrapped into unique coroutine objects we don't have to worry and we can code more naturally.

So I hope this illustrates the mindset of this system. Snapping smaller fairly isolated pieces of functionality together to get complex functionality. Maintaining each component is extremely easy since thier code is usually fairly small and it's contained in its own "class" and file. Removing its effects is simply commenting out its event hookups which are usually just a couple of lines of code.

The only "coupling" components have is through the arguments. You need to know what variable names are part of the args table from within a components action when you hook up to an event. It's as loose of coupling you can get. It doesn't have anything to directly do with components structure themselves. I remember when josh first started this version of Leadwerks where he allowed multiple scripts to be attached. He found himself querying the other attached scripts to see if a certain script existed and then directly calling its functions. He didn't like that and he was right. That sort of defeats the purpose of components being isolated and creates a spaghetti mess of code. People in Unity still do this and I think it's a mess, and bug prone issue. Once you start working with hooking up actions to events things just become so much easier to work with.

Learning what size scope to make your components (not too big not too small in scope) takes a little practice and feel but once you get the feeling down you are off and rolling.