Authoring a Brush Entity

From Valve Developer Community
Revision as of 14:05, 4 December 2005 by Maven (talk | contribs) (Create The FGD Entry)
Jump to: navigation, search

Our last example dealt with giving entities a model. Here we’ll use world architecture (or brushes) to represent our entity and how it collides and moves around the world. We’ll also look at the touch function, available to all entities. This will let us make the entity move when touched.

Create a .CPP file for the new entity

Add the source file to the server.dll project by right-clicking.

  • Create a file named sdk_brushentity.cpp. The file should go under the dlls folder under your source code folder. For example, if you installed the source code into C:\MyMod\src, then you would create a file called C:\MyMod\src\dlls\sdk\sdk_brushentity.cpp.
  • Next, copy this code and paste it into this new file.
  • Last, add this file to your server.dll project. If you opened the game_sdk.sln solution, then you can right-click on the hl project in the Solution Explorer window and choose Add, then Add Existing Item.

Walking through the code

Creating the Class Definition

class CMyBrushEntity : public CBaseToggle
{
public:
       DECLARE_CLASS( CMyBrushEntity, CBaseToggle );
       DECLARE_DATADESC();

       void Spawn( void );
       bool CreateVPhysics( void );

       void BrushTouch( CBaseEntity *pOther );
};

We descend our new entity from the CBaseToggle class. This class has some basic functions to help us move our brush entity through the world.

Defining the Data Description

LINK_ENTITY_TO_CLASS( my_brush_entity, CMyBrushEntity );

// Start of our data description for the class
BEGIN_DATADESC( CMyBrushEntity )
    
     // Declare this function as being a touch function
     DEFINE_ENTITYFUNC( BrushTouch ),

END_DATADESC()

Here we simply declare our touch function that we’ll use. See the Data Description Table Document for more information.

Create the Spawn() function

void CMyBrushEntity::Spawn( void )
{
       // We want to capture touches from other entities
       SetTouch( &CMyBrushEntity::BrushTouch );

       // We should collide with physics
       SetSolid( SOLID_VPHYSICS );
      
       // We push things out of our way
       SetMoveType( MOVETYPE_PUSH );
      
       // Use our brushmodel
       SetModel( STRING( GetModelName() ) );

       // Create our physics hull information
       CreateVPhysics();
}

The first thing we do in this block is setup our touch function to point to BrushTouch() where we’ll do our movement code. Next we tell the entity to use SOLID_VPHYSICS so we’ll use our exact bounds to collide. Setting the entity to MOVETYPE_PUSH means that we’ll attempt to move entities out of our way, instead of just being blocked.

In this example we use the SetModel() with our model name from the editor. In this case it tells the entity to use its brush model, as defined in the map.

bool CMyBrushEntity::CreateVPhysics( void )
{
       // For collisions with physics objects
       VPhysicsInitShadow( false, false );

       return true;
}

Finally, we call CreateVPhysics() to setup our collision shadow. This is what we’ll use to collide with physics objects in the world. Without this, the brush would pass through those objects.

Create the BrushTouch() function

The entity has been told to notify us when its been touched, via the BrushTouch() function. When we receive this notification, we’ll cause the entity to move away from the entity that touched it. To do this, we’ll need information about the events surrounding the touch. This information is provided in the trace_t structure, returned by the GetTouchTrace() function. This returns the actual trace collision that generated the event.

void CMyBrushEntity::BrushTouch( CBaseEntity *pOther )
{
     // Get the collision information
     const trace_t &tr = GetTouchTrace();

     // We want to move away from the impact point along our surface
     Vector vecPushDir = tr.plane.normal;
     vecPushDir.Negate();
     vecPushDir.z = 0.0f;

     // Move slowly in that direction
     LinearMove( GetAbsOrigin() + ( vecPushDir * 64.0f ), 32.0f );
}

First we retrieve the normal of the surface that was hit. In our case, this will be one of the planes of the brush entity. We negate that value to point towards the direction of the impact, and then remove the Z component of the direction to keep us parallel to the floor.

Finally, we use the LinearMove() function to cause the brush to move to a location at a given speed. The LinearMove() function is implemented by CBaseToggle and takes care of behind-the-scenes maintenance in how the brush model moves.

Create The FGD Entry

To use the entity within Hammer, we’ll need to create an entry in our FGD file. Hammer will use this data to interpret the various keyvalues and functions the entity is exposing. See the FGD Format document for more information about FGD files.

The FGD entry allows you to assign the entity to a brush.

@SolidClass base(Targetname) = my_brush_entity : "Tutorial brush entity."
[
	
]

Be sure to add the line @include "base.fgd" at the top of the FGD file, which provides Hammer with some necessary functions. (That is appropriate for a total conversion. For a mod based on existing content, include the appropriate FGD instead; eg, for an HL2 mod, include halflife2.fgd instead of base.fgd.)