Data Descriptions

From Valve Developer Community
Jump to navigation Jump to search

Data description tables contain metadata. They have many uses, but the most common is to define what internal information about a class should be stored when the game is saved.

Usage

A Datadesc table must be declared in the constructor with DECLARE_DATADESC();. Table elements are then declared between BEGIN_DATADESC and END_DATADESC, outside any functions: 

BEGIN_DATADESC( CMyClass )

   DEFINE_FIELD( ... ),
   DEFINE_FIELD( ... ),

END_DATADESC()

Note the absence of semicolons.

Example

For npc_barnacle: 

BEGIN_DATADESC( CNPC_Barnacle )

	DEFINE_FIELD( m_flAltitude, FIELD_FLOAT ),
	DEFINE_FIELD( m_cGibs, FIELD_INTEGER ),// barnacle loads up on gibs each time it kills something.
	DEFINE_FIELD( m_bLiftingPrey, FIELD_BOOLEAN ),
	DEFINE_FIELD( m_bSwallowingPrey, FIELD_BOOLEAN ),
	DEFINE_FIELD( m_flDigestFinish, FIELD_TIME ),
	DEFINE_FIELD( m_bPlayedPullSound, FIELD_BOOLEAN ),
	DEFINE_FIELD( m_bPlayerWasStanding, FIELD_BOOLEAN ),
	DEFINE_FIELD( m_flVictimHeight, FIELD_FLOAT ),
	DEFINE_FIELD( m_iGrabbedBoneIndex, FIELD_INTEGER ),

	DEFINE_FIELD( m_vecRoot, FIELD_POSITION_VECTOR ),
	DEFINE_FIELD( m_vecTip, FIELD_POSITION_VECTOR ),
	DEFINE_FIELD( m_hTongueRoot, FIELD_EHANDLE ),
	DEFINE_FIELD( m_hTongueTip, FIELD_EHANDLE ),
	DEFINE_FIELD( m_hRagdoll, FIELD_EHANDLE ),
	DEFINE_AUTO_ARRAY( m_pRagdollBones, FIELD_MATRIX3X4_WORLDSPACE ),
	DEFINE_PHYSPTR( m_pConstraint ),
	DEFINE_KEYFIELD( m_flRestUnitsAboveGround, FIELD_FLOAT, "RestDist" ),
	DEFINE_FIELD( m_nSpitAttachment, FIELD_INTEGER ),
	DEFINE_FIELD( m_hLastSpitEnemy, FIELD_EHANDLE ),
	DEFINE_FIELD( m_nShakeCount, FIELD_INTEGER ),
	DEFINE_FIELD( m_flNextBloodTime, FIELD_TIME ),
#ifndef _XBOX
	DEFINE_FIELD( m_nBloodColor, FIELD_INTEGER ),
#endif
	DEFINE_FIELD( m_vecBloodPos, FIELD_POSITION_VECTOR ),
	DEFINE_FIELD( m_flBarnaclePullSpeed, FIELD_FLOAT ),
	DEFINE_FIELD( m_flLocalTimer, FIELD_TIME ),
	DEFINE_FIELD( m_vLastEnemyPos, FIELD_POSITION_VECTOR ),
	DEFINE_FIELD( m_flLastPull, FIELD_FLOAT ),
	DEFINE_EMBEDDED( m_StuckTimer ),

	DEFINE_INPUTFUNC( FIELD_VOID, "DropTongue", InputDropTongue ),
	DEFINE_INPUTFUNC( FIELD_INTEGER, "SetDropTongueSpeed", InputSetDropTongueSpeed ),

#ifdef HL2_EPISODIC
	DEFINE_INPUTFUNC( FIELD_VOID, "LetGo", InputLetGo ),
	DEFINE_OUTPUT( m_OnGrab,     "OnGrab" ),
	DEFINE_OUTPUT( m_OnRelease, "OnRelease" ),
#endif

	// Function pointers
	DEFINE_THINKFUNC( BarnacleThink ),
	DEFINE_THINKFUNC( WaitTillDead ),

	DEFINE_FIELD( m_bSwallowingBomb, FIELD_BOOLEAN ),

END_DATADESC()

Element types

DEFINE_FIELD

This macro definition is used for saving and loading in the engine. Any member variable properly defined in this macro will be saved and restored automatically. The macro is declared as: 

DEFINE_FIELD( variableName, variableType )

The variableType parameter can be:

FIELD_VOID
No type or value (used for function parameters)
FIELD_FLOAT
Any floating point value
FIELD_STRING
A string ID (return from ALLOC_STRING)
FIELD_VECTOR
Any vector, QAngle, or AngularImpulse
FIELD_QUATERNION
A quaternion value
FIELD_INTEGER
Any integer or enum value
FIELD_BOOLEAN
Boolean value (represented as an integer)
FIELD_SHORT
2 byte integer
FIELD_CHARACTER
One byte
FIELD_COLOR32
8-bit per channel [R,G,B,A] (32-bit color)
FIELD_EMBEDDED
An embedded object with a data description, recursively traverse and embedded | class/structure based on anadditional type description
FIELD_CUSTOM
A special type that contains function pointers to its read/write/parse functions
FIELD_CLASSPTR
CBaseEntity pointer
FIELD_EHANDLE
Entity handle
FIELD_EDICT
edict_t pointer
FIELD_POSITION_VECTOR
A world coordinate value, which is fixed up across level-transitions automatically
FIELD_TIME
A floating point time value, which is fixed up across level-transitions automatically
FIELD_TICK
An integer tick count, which is fixed up similarly to FIELD_TIME
FIELD_MODELNAME
Engine string that is a model name (Must be precached)
FIELD_SOUNDNAME
Engine string that is a sound name (Must be precached)
FIELD_INPUT
A list of inputted data fields, all derived from CMultiInputVar
FIELD_FUNCTION
A class function pointer (Think, Use, etc.)
FIELD_VMATRIX
A VMatrix
Note.pngNote:Output coordinates are NOT worldspace
FIELD_VMATRIX_WORLDSPACE
A VMatrix that maps some localspace to worldspace (translation is fixed up on level-transitions)
FIELD_MATRIX3X4_WORLDSPACE
matrix3x4_t that maps some localspace to worldspace (translation is fixed up on level-transitions)
FIELD_INTERVAL
A start and range floating point interval ( e.g., 3.2->3.6 == 3.2 and 0.4 )
FIELD_MODELINDEX
A model index
FIELD_MATERIALINDEX
A material index (using the material precache string table)

DEFINE_KEYFIELD

This macro works in the same manner as DEFINE_FIELD with regards to saving and restoring data members. It extends this functionality by also defining a reference name for the data member which links it to the keyvalue identifier defined in the FGD entry for an entity class. Once this is properly declared, the data member will be initialized to the value defined in the map upon that entity’s creation. 

DEFINE_KEYFIELD( variableName, variableType, "keyvalueName" )

As an example, the following definition would link the m_bEnabled data member to the "enabled" keyvalue identifier in Hammer. 

DEFINE_KEYFIELD( m_bEnabled, FIELD_BOOLEAN, "enabled" )
Note.pngNote:The keyvalue’s identifying name is case insensitive.

DEFINE_OUTPUT

This macro is used to link an output event to a named identifier used by Hammer. It is defined as: 

DEFINE_OUTPUT( outputVariable, outputName )
Note.pngNote:The outputEventVariable in this case must be of type COuputEvent.

DEFINE_INPUTFUNC

This macro is used to link named inputs from Hammer to functions in the engine. This also defines the type of parameter being passed in to the function from the Entity I/O system. The macro is defined as: 

DEFINE_INPUTFUNC( parameterType, "inputName", InputFunction )

The parameterType can be any of the following FIELD_ types:

  • FIELD_VOID
  • FIELD_INTEGER
  • FIELD_FLOAT
  • FIELD_STRING
  • FIELD_VECTOR
  • FIELD_COLOR32
  • FIELD_BOOLEAN

DEFINE_INPUT

This macro is a shorthand version of DEFINE_INPUTFUNC. It automatically sets the described data member to the parameter passed in from the Input() function. This bypasses the need to create an input function whose sole purpose is to set a data member to a passed value. The macro is declared as: 

DEFINE_INPUT( variableName, variableType, "keyvalueName" )

DEFINE_ARRAY AND DEFINE_AUTO_ARRAY

As their names suggest, these macros deal with saving and restoring array values. The number of elements in the array must be declared when using DEFINE_ARRAY, whereas DEFINE_AUTO_ARRAY will cause the code to automatically determine the size of the array at compile time.

The macros are declared as: 

DEFINE_ARRAY( variable, variableType, numElements )

DEFINE_AUTO_ARRAY( variable, variableType )

DEFINE_CUSTOM_FIELD

This macro allows custom interpretation of a variable with regards to how it is saved and restored. By passing in the reference to a handler class, the user is able to handle serialization of the data entirely.

The handler class must descend from the CClassPtrSaveRestoreOps class; it uses the Save() and Restore() functions for serialization.

For more information, see uses of CClassPtrSaveRestoreOps within the code base.

DEFINE_THINKFUNC

Entities using a custom think function must declare that function via this macro declaration.

Think functions must be of the type: 

typedef void (*ThinkFunc)( void);

DEFINE_ENTITYFUNC

Entities using a custom touch function must declare that function via this macro declaration.

Touch functions must be of the type: 

typedef void (CBaseEntity::*ENTITYFUNCPTR)(CBaseEntity *pOther );

DEFINE_USEFUNC

Entities using a custom use function must declare that function via this macro declaration.

Use functions must be of the type: 

typedef void (*UseFunc)(
	CBaseEntity *pActivator,
	CBaseEntity *pCaller,
	USE_TYPE useType,
	float value
);

Others

  • dlls\simtimer.h
  • game_shared\physics_saverestore.h
    • DEFINE_PHYSPTR - Define a physics pointer
    • DEFINE_PHYSPTR_ARRAY - Define a physics pointer array
  • game_shared\saverestore_bitstring.h
  • game_shared\saverestore_utlmap.h
  • game_shared\saverestore_utlrbtree.h
  • game_shared\saverestore_utlvector.h
  • game_shared\soundenvelope.h
    • DEFINE_SOUNDPATCH
  • public\saverestore.h
    • DEFINE_KEYFIELD_NOT_SAVED
    • DEFINE_ENTITY_FIELD
    • DEFINE_ENTITY_GLOBAL_FIELD
    • DEFINE_GLOBAL_FIELD
    • DEFINE_GLOBAL_KEYFIELD
    • DEFINE_CUSTOM_FIELD
    • DEFINE_CUSTOM_KEYFIELD
    • DEFINE_AUTO_ARRAY2D
    • DEFINE_EMBEDDED
    • DEFINE_EMBEDDED_OVERRIDE
    • DEFINE_EMBEDDEDBYREF
    • DEFINE_EMBEDDED_ARRAY
    • DEFINE_EMBEDDED_AUTO_ARRAY
    • DEFINE_PRED_TYPEDESCRIPTION
    • DEFINE_PRED_TYPEDESCRIPTION_PTR
    • DEFINE_PRED_FIELD
    • DEFINE_PRED_ARRAY
    • DEFINE_FIELD_NAME
    • DEFINE_PRED_FIELD_TOL
    • DEFINE_PRED_ARRAY_TOL
    • DEFINE_FIELD_NAME_TOL
  • public\stdstring.h
    • DEFINE_STDSTRING

Template:Otherlang:en Template:Otherlang:en:ru

Retrieved from "https://developer.valvesoftware.com/w/index.php?title=Data_Descriptions&oldid=118702"