Authoring a Logical Entity

Logical entities are the simplest of entities because they have no position in the world, no visual component, and only exist to service input from other entities. math_counter for example stores a value that can be added to or subtracted from; other entities in the map can modify the data with inputs or receive information from it with an output.

In this tutorial we'll create a logical entity that performs the simple task of storing a value and incrementing that value every time it receives the appropriate input. Once the counter has reached a value we'll define, the entity will fire an output.

Create the source file

This tutorial assumes you are using Visual Studio. See Compiler Choices.

Add a new .cpp file to Sever/Source Files/ and call it sdk_logicalentity. Giving each entity its own .cpp reduces overhead, since it allows the compiler to separate your code into more discrete segments, and speeds compiling, since only .cpp files that have changed need to be re-compiled.

Includes

To get anywhere with our code we need to let the compiler know what "libraries" we are going to be calling on. Consider the commands we are going to be using to be books from these libraries. Insert this line of code:

#include "cbase.h"

cbase.h provides Valve's basic set of commands for creating entities. Since we are creating their very simplest form, we only need the one base library. In more complex cases there can be many, many different includes.

The opening "c" means that this is a server-side library, and the closing ".h" means that it's a header file instead of a full .cpp - but don't worry about that for now.

Declaring the class

This section will be quite long, but once you're finished with it you'll have a grasp on the outline of all C++ code.

In C++, instructions are handled by "objects". Think of them as the librarians of our ongoing ananlogy.

Objects are created from templates like the one we are about to define:

class CMyLogicalEntity : public CLogicalEntity
{
public:
	DECLARE_CLASS( CMyLogicalEntity, CLogicalEntity );
	...
};

This whole process is known as "declaring a class" (not just the DECLARE_CLASS command, despite its name!). Every version of your entity in the world is another "instance" of this template. The same is true of every entity: every Combine Soldier you've ever seen running around is an independent instance of the same C++ class.

In the first line of code, we start by saying that we're declaring class with the class command. We then give it a name, CMyLogicalEntity, and then with the colon tell the compiler that it is "inheriting" from Valve's pre-existing CLogicalEntity class (that we can reach thanks to our include of cbase.h earlier).

Inheriting means that we're working on a copy of the original class, overriding and extending it instead of starting entirely from scratch or changing the original class itself. It's almost exactly like copying a file on your desktop: you get the contents of the original, and can edit it separately.

We then open a set of square parathenses. This means that all of the instructions inside are members of this class. Note how there isn't a line-ending semicolon here. We're still, technically, writing the same line of code.

Next is "public:", which means that the commands coming up will need to interact with other .cpp files (We'll make some private commands in a moment). Each public command creates a little more overhead and increases the potential for nasty bugs, as well as adding another thing you have to think about when trying to interact with the class somewhere else. Only commands that really need to be public should be.

The first command

Now - finally - we have the framework up and running and can start issuing commands. DECLARE_CLASS is a 'macro' created by Valve to automate much of the book-keeping that needs to be done when declaring a new class.

The round parentheses mean that we are passing "arguments", or "parameters", to it: to continue our analogy, we're saying (in this case) what book we want filing and where it belongs. If you're being observant you will already have noticed that we are sending it the same key information that's in the first line, separated, or "delimited", with a comma.

This command means that when the class is initialised as your mod starts, somewhere else in the codebase a predefined class is performing lots of obscure and tedious legwork for you. The closing semicolon tells the compiler that this is the end of a command and a new one is about to start (line breaks and whitespace aren't taken into account - the compiler just sees a continuous stream of characters).

Closing the declaration (ahead of time)

Don't type the ellipsis (...) - it's only there to show you where the rest of the declaration code will go. We're going to skip ahead for a moment instead and end the class command with };. It's simple enough: the closing bracket counters the opening one we typed earlier, and the semicolon performs the same function as it did after DECLARE_CLASS.

Note:You don't normally need both } and ;, as the former implies the latter. The class command is a special case.

Declaring a DATADESC, constructor and function

Now go back to where the ellipsis was and add these new lines:

	DECLARE_DATADESC();

	// Constructor
	CMyLogicalEntity ( void ) : m_nCounter( 0 ) {}

	// Input function
	void InputTick( inputdata_t &inputData );

The first line is another macro, this time that automates the process of declaring a DATADESC table we'll be adding later. Thanks to the // the second is a commented line that is ignored by the compiler but helps people reading your code (including you, when you come back to it after a lengthy enough break) understand its meaning.

The third is declaring the class "constructor": an instance of your class within your class that "bootstraps" it into existence when triggered.

I don't have a good idea of what's going on after the colon, someone please help.

Lastly, we create our first "function". This is a collection of commands that are "called", or "executed", in one batch. In this case, our function will be called whenever an input is received and, if you remember back to our original goal, increment our stored value by 1. void means that the function won't return a value to the class elsewhere on the server that called it. The I/O output goes via a different route, and the remote class doing the calling wouldn't know what to do with a returned value anyway.

We call this function InputTick and define the "parameters" it requires. In this case, one inputdata_t value named &inputData (The & makes it a "pointer", but don't worry about that). This is information about the map entity that triggered the input that is automatically generated by the engine at run-time.

Private declarations

Now we are declaring private objects. These won't be accessible anywhere outside this class unless we make them so in a public function (which we won't).

private:

	int	m_nThreshold;	// Count at which to fire our output
	int	m_nCounter;	// Internal counter

	COutputEvent	m_OnThreshold;	// Output event when the counter reaches the threshold

The first two of these are "variables". They are buckets in the computer's physical memory that can be filled with a value, used in calculations, passed around, perhaps written to the disk, and emptied. They are "integer" or "int" variables which can be used to store whole numbers like 1, 2, 3, and so on. They can't store things like words of characters however, and can't store numbers with decimal points. C++ is very strict about these kinds of things!

m_OnThreshhold is an instance of a class Valve have already written for you in cbase.h, COutputEvent. You'll use it in InputTick to pass a value through the I/O system when our conditions are met. (It's actually a variable, like int, only a custom one that doesn't come with the compiler. The only reason it isn't coloured blue as well is that Visual Studio doesn't recognise it.)

A word about the names in this section. m_ means that the objects are members of a class, while n means that the value is numeric. You don't have to follow these naming conventions, but it is strongly recommended.

Check back

That's the declaration finished. Check back over what you've written and make sure it's the same as the reference code. If it is, you're ready to move past that }; and into the body of the entity's code.

Linking the class to an entity name

We are now past the class declaration. In Visual Studio, you should be able to collapse that whole section by clicking on the second minus sign in the margin. Now, after the };, enter this:

LINK_ENTITY_TO_CLASS( my_logical_entity, CMyLogicalEntity );

This is another macro (you can tell from the capitals) that is giving the class an "entity name". The programming code doesn't refer to the entity by the same name that the I/O system and Hammer does for reasons that you'll understand later.

Data description table

The data description table is a macro that gives source metadata about each member of the class. The comments should explain what each does: DEFINE_FIELD, for instance, ensures that the counter and threshold values are stored in a saved game and prevents them from resetting to zero every time it is loaded.

This code has examples of brown "string" values. Unlike the other commands, these are simply data that the compiler accepts, stores, and blindly exposes to the engine. You can put anything you like between the quote marks and the code will compile, but when it comes to actually instancing the entity Source will be confused unless it's correct.

// Start of our data description for the class
BEGIN_DATADESC( CMyLogicalEntity  )
	
	// For save/load
	DEFINE_FIELD( m_nCounter, FIELD_INTEGER ),

	// Links our member variable to our keyvalue from Hammer
	DEFINE_KEYFIELD( m_nThreshold, FIELD_INTEGER, "threshold" ),

	// Links our input name from Hammer to our input member function
	DEFINE_INPUTFUNC( FIELD_VOID, "Tick", InputTick ),

	// Links our output member to the output name used by Hammer
	DEFINE_OUTPUT( m_OnThreshold, "OnThreshold" ),

END_DATADESC()

You'll have noticed that while our input is a function, our output is that COutputEvent variable we declared earlier. This is because, once generated, an output leaves the class it originates from immediately and requires no processing from it.

When you're writing your own datadesc tables, remember to include a comma after each DEFINE_* command.

Note:There are no semicolons here. This is extremely unusual!

Creating the input function

Now we are going to "define" our input function. This is the last step. Notice that the first line is identical to the one we entered in the class declaration, except for the addition of CMyLogicalEntity::. This ensures it is associated with the correct class. In this case there is only one class in the .cpp for it to be associated with, but there can be many.

//-----------------------------------------------------------------------------
// Purpose: Handle a tick input from another entity
//-----------------------------------------------------------------------------
void CMyLogicalEntity::InputTick( inputdata_t &inputData )
{
	// Increment our counter
	m_nCounter++;

	// See if we've met or crossed our threshold value
	if ( m_nCounter >= m_nThreshold )
	{
		// Fire an output event
		m_OnThreshold.FireOutput( inputData.pActivator, this );
		
		// Reset our counter
		m_nCounter = 0;
	}
}

Here's what's going on within the function:

m_nCounter++

C++ shorthand for "increment by one". In full, it would be m_ncounter = m_ncounter + 1.

if ( m_nCounter >= m_nThreshold )

if statements need an equation to evaluate. > means greater than, so combined with = we have an "operator" that says "greater than or equal to". If out counter is greater than or equal to our threshold, execute whatever is inside this command.

{ and }

This is a "nested" pair of square parentheses. It groups all of the commands the if statement will execute. There can be as many levels of nesting as is needed, but be sure to keep track of them all!

m_OnThreshold.FireOutput

You probably pasted this in. Delete it and type it out in full, and note what happens when you reach the dot. You are calling a public function of the m_OnThreshold instance of the COutputEvent class, and Visual Studio helps you by providing a list of the possible options. Keep typing to filter it, or use up/down and return to select an item.

If we were to directly call this class' InputTick function from elsewhere, we would type MyLogicalEntity1.InputTick(<arguments>), where MyLogicalEntity1 is the name of the instance we were targeting.

( inputData.pActivator, this )

These are the arguments we are passing to the COutputEvent. They will be automatically generated by Source, and arrive at our function through the parameters we declared on its first line.

We're sending:

1. The entity that started this whole chain off (in Source lingo the "activator").
2. The entity that the call is being sent from, the "caller", which is "this" one.

These are needed for targetname keywords.

m_nCounter = 0

If we didn't reset our counter, the number would only keep on going up!

Congratulations, the entity is ready to be compiled. If you receive any errors from Visual Studio, check the reference code!

We can't use this entity directly from the engine however - if you've ever made a map, you'll know there's a lot of I/O information that we haven't made room for in this code. Thankfully our DATADESC table allows Source to plug this entity into the wider I/O system. The only thing left to do is tell Hammer about the entity, so that we can control it from a map.

Create The FGD Entry

An FGD is a text file that defines both what entities your mod has available and what can be done with them. This isn't a perfect world and Hammer won't read from the mod code itself, so it's important to keep the FGD up to date.

If you don't already have an FGD, save an empty text file under your mod's folder as <modname>.fgd. Then load Hammer and visit Tools > Options. Making sure your mod is the active configuration, click the "Add" button and navigate to your FGD.

FGDs are a different topic, so this won't be covered in detail. Just paste the following code in:

@PointClass base(Targetname) = my_logical_entity : "Tutorial logical entity."
[
	threshold(integer) : "Threshold" : 1 : "Threshold value."
	input Tick(void) : "Adds one tick to the entity's count."
	output OnThreshold(void) : "Threshold was hit."
]

If you're making a mod from scratch and won't be using halflife2.fgd, be sure to add the line @include "base.fgd" to the top.

And there you have it! Your entity is now ready for use.

See Also

• C++ code in full
• My First Entity