Ru/Authoring a Model Entity

Предполагается что вы прочли и полностью поняли статью Authoring a Logical Entity(en).

В этой статье мы создадим объект (объект = entity), который может двигаться, сталкиваться с другими объектами, и который отображается в игре (в виде модели). Мы заставим наш объект случайным образом перемещаться по миру.

Создайте файл sdk_modelentity.cpp в вашей персональной папке в серверном проекте и мы начнем.

Включение заголовочного файла и описание класса

Сейчас вы должны понимать следующий код:

#include "cbase.h"

class CMyModelEntity : public CBaseAnimating
{
public:
	DECLARE_CLASS( CMyModelEntity, CBaseAnimating );
	DECLARE_DATADESC();

	CMyModelEntity()
	{
		m_bActive = false;
	}

	void Spawn( void );
	void Precache( void );

	void MoveThink( void );

	// Входная функция
	void InputToggle( inputdata_t &inputData );

private:

	bool	m_bActive;
	float	m_flNextChangeTime;
};

Заметьте что на этот раз мы наследуем наш класс от CBaseAnimating(en), и на этот раз у нас появилось несколько новых функций. В закрытой (private) части класса содержатся две переменные: bool - это тип переменной которая может принимать только значения правда/ложь (true/false) (1/0), а переменные типа float могут хранить в себе числовые значения с десятичной точкой.

Примечание:Наш объект не начнёт двигаться пока не получит соответствующую команду от InputToggle(). Заставить объект двигаться можно только вызовом функции InputToggle() (а не простой установкой значения m_bActive в единицу) - это станет неплохой практикой после того как вы прочтёте статью.

Имя объекта и таблица описания данных

LINK_ENTITY_TO_CLASS( my_model_entity, CMyModelEntity );

// Начало описания данных класса.
BEGIN_DATADESC( CMyModelEntity )
	
	// Сохранение/загрузка состояния объекта.
	DEFINE_FIELD( m_bActive, FIELD_BOOLEAN ),
	DEFINE_FIELD( m_flNextChangeTime, FIELD_TIME ),

	// Присвоение нашей входной функции имя в Hammer'e.
	DEFINE_INPUTFUNC( FIELD_VOID, "Toggle", InputToggle ),

	// Объявление "мыслительной" (think) функции.
	DEFINE_THINKFUNC( MoveThink ),

END_DATADESC()

Самое большое отличие от созданного нами ранее логического объекта в наличии макроса DEFINE_THINKFUNC, который даёт движку Source знать о, так называемой "мыслительной"(en) функции.

Определение модели

// Имя модели нашего объекта.
#define	ENTITY_MODEL	"models/gibs/airboat_broken_engine.mdl"

Этот код жёстко задаёт модель(en), которую наш объект будет отображать в игре. Это статический кусок информации - не переменная: это значение не может меняться после компиляции кода. Путь к .mdl-файлу задаётся относительно директории игры (например hl2/).

Примечание:Мы создали эту строку только для того чтобы упростить поиск и замену этого значения в будущем. Она не влияет на работу нашего кода.

Функция Precache()

Мы добрались до первой функции. Функция Precache()(en) вызывается при появлении объекта на карте и гарантирует загрузку всего, что в ней перечислено до того как появится игрок (т.е. до того как он увидит мир и получит контроль над игрой). Смотрите рекомендации по прекэшированию(en) для получения дополнительной информации.

Прекэширование получило отдельное имя потому что существуют другие типы "асинхронной(en)" загрузки, которые могут выполняться после появления игрока.

//-----------------------------------------------------------------------------
// Назначение: Прекэширование необходимых объекту ресурсов.
//-----------------------------------------------------------------------------
void CMyModelEntity::Precache( void )
{
	PrecacheModel( ENTITY_MODEL );

	BaseClass::Precache();
}

Для данного объекта мы прекэшируем модель, которую будем использовать, а затем вызываем функцию прекэширования нашего базового класса (которая в случае класса CBaseAnimating обеспечивает загрузку системы частиц для огня, т.к. каждый объект с моделью в игре может загореться). Другие команды прекэширования: PrecacheParticleSystem()(en) и PrecacheScriptSound()(en)

Функция Spawn()

Функция Valve Spawn()(en) вызывается всякий раз когда создаётся новый экземпляр объекта, примерно так же, как и конструктор. Вообще можно использовать функцию Spawn() вместо конструктора, но из соображений управляемости рекомендуется использовать и конструктор чтобы отделять инициализацию переменных от остального кода.

//-----------------------------------------------------------------------------
// Назначение: Настраивает начальное состояние объекта.
//-----------------------------------------------------------------------------
void CMyModelEntity::Spawn( void )
{
	Precache();

	SetModel( ENTITY_MODEL );
	SetSolid( SOLID_BBOX );
	UTIL_SetSize( this, -Vector(20,20,20), Vector(20,20,20) );
}

Сначала мы вызываем функцию Precache(), а затем идут вызовы различных функций класса CBaseAnimating. Функция SetModel()(en) задаёт модель объекта. В скобках ей передаётся определённый нами ранее путь к модели объекта. Функция SetSolid()(en) требует более подробных разъяснений. Она определяет форму, которую наш объект будет использовать для проверки на столкновение с другими объектами. Использование формы самой модели было бы очень, очень дорогим(en) по отношению к ресурсам компьютера, поэтому движок Source предлагает несколько компромиссов:

SOLID_NONE

"Прозрачный" (не твердый) объект.

SOLID_BBOX

Используется ориентированный по осям ограничивающий короб.

SOLID_BSP

Используется BSP-дерево для определения твёрдости (используется в брашах(en)).

SOLID_CUSTOM

Объект использует свои собственные функции для проверки на столкновения.

SOLID_VPHYSICS

Для определения точных столкновений используется встроенная в модель модель столкновений(en).

Эти пункты выбираются на уровне движка и авторы модов не могут добавлять или менять их. Мы используем параметр SOLID_BBOX(en), который генерирует "ограничивающий короб(en)", размер которого движок определяет так, чтобы он охватывал всю модель. Более "дорогой" параметр SOLID_VPHYSICS(en), который использует встроенную в модель модель столкновений(en), не поддерживает низкоуровневые функции перемещения, которые мы будем использовать для нашего объекта, поэтому мы его не применяем.

Вызов UTIL_SetSize()(en) нужен для того, чтобы сделать наш ограничивающий короб кубическим. Это сделано потому, что каким бы странным это не казалось, ограничивающий короб не может вращаться. Вам понадобится vphysics-обработка столкновений если вы захотите заставить модель вращаться. А по описанным выше причинам мы её не используем.

Предупреждение:Spawn() вызывается незамедлительно после создания объекта. Если это случится сразу же после создания карты нет гарантии того, что на карте уже появились другие объекты. Поэтому любой код, который предполагает что объект будет связываться с другими игровыми объектами становится ненадежным. В таких случаях используйте функцию Activate()(en), которая всегда вызывается после появления всех объектов.

Функция MoveThink()

"Мыслительная" функция(en) (to think - думать) позволяет объекту "принимать решения" без побуждения со стороны внешнего кода. Вспомните про наш логический объект - он делал что-нибудь только при задействовании его входной функции; это не подходит для объектов, которые должны определенным образом перемещаться по миру. Мыслительная функция, если она присутствует, обычно является центральной функцией в коде объекта.

Сейчас мы создаём мыслительную функцию, которая будет вызываться движком с периодичностью 20 раз в секунду. Это может показаться большим числом, однако современные процессоры очень быстрые, а наш объект очень простой. Вы сможете добавить очень большое кол-во объектов CMyModelEntity на карту без большой потери производительности.

//-----------------------------------------------------------------------------
// Назначение: Мыслительная функция для случайного перемещения объекта по карте.
//-----------------------------------------------------------------------------
void CMyModelEntity::MoveThink( void )
{
	// Смотрим, должны ли мы снова поменять направление.
	if ( m_flNextChangeTime < gpGlobals->curtime )
	{
		// Задаём случайное направление и скорость.
		Vector vecNewVelocity = RandomVector( -64.0f, 64.0f );
		SetAbsVelocity( vecNewVelocity );

		// Сменить направление снова через 1-3 секунды.
		m_flNextChangeTime = gpGlobals->curtime + random->RandomFloat( 1.0f, 3.0f );
	}

	// Поворот объекта туда, куда идет движение.
	Vector velFacing = GetAbsVelocity();
	QAngle angFacing;
	VectorAngles( velFacing, angFacing );
 	SetAbsAngles( angFacing );

	// Запускать эту функцию с частотой 20Hz
	SetNextThink( gpGlobals->curtime + 0.05f );
}

Несмотря на то, что в этой функции довольно много кода, она довольно простая. Когда случайный интервал времени подходит к концу объект выбирает новые случайные направление и скорость для продолжения движения. Также меняются углы положения объекта в пространстве, чтобы они соответствовали новому направлению движения. Это происходит для трех измерений.

Дополнительная информация:

• gpGlobals(en)->curtime возвращает время, в которое исполняется текущий код, как значение с плавающей точкой.
• Вектор - это набор переменных, используемых для определения движения, которые содержат в себе данные о направлении и скорости. Функция SetAbsVelocity()(en) задаёт абсолютную скорость,
• QAngle(en) это просто угол - т.е. то же самое что вектор только без данных о скорости. QAngle(en) задаёт направление.
• Функция VectorAngles()(en) преобразует вектор (velFacing) в угол (angFacing). Не забывайте, что С++ очень строг в отношении типов: вам понадобятся утилитарные функции, такие как VectorAngles(), чтобы осуществлять преобразования между двумя типами.

В конце мы вызываем функцию SetNextThink()(en), которая указывает когда в следующий раз необходимо вызвать мыслительную функцию. Здесь мы задаём новую обработку через 0.05 секунд (1/20 часть), однако это число может быть различным для разных объектов. Важно понимать, что если не вызвать функцию SetNextThink() объект перестанет "мыслить".

Вы могли отметить, что здесь мы определяли новые переменные. Так же как и переменные, определенные внутри класса, переменные, определенные внутри функции, принадлежат данной функции. Они создаются каждый раз когда вызывается функция и уничтожаются по её завершении.

Совет:На самом деле нам не очень то и нужна переменная vecNewVelocity. Попробуйте передать значение в функцию SetAbsVelocity() без создания лишней переменной. Вспомните почему мы добавляем void перед всеми нашими функциями.

InputToggle()

Мы добрались до нашей последней функции. Это входная функция, которая будет включать и выключать передвижение объекта.

//-----------------------------------------------------------------------------
// Назначение: Включать/выключать движение объекта.
//-----------------------------------------------------------------------------
void CMyModelEntity::InputToggle( inputdata_t &inputData )
{
	// Переключение состояния активности.
	if ( !m_bActive )
	{
		// Начало мыслительного процесса.
		SetThink( &CMyModelEntity::MoveThink );

		SetNextThink( gpGlobals->curtime + 0.05f );
		
		// Начать летать.
		SetMoveType( MOVETYPE_FLY );

		// Установка времени для смены направления и скорости.
		m_flNextChangeTime = gpGlobals->curtime;

		// Изменение переменной m_bActive для отображения текущего состояния.
		m_bActive = true;
	}
	else
	{
		// Перестать мыслить.
		SetThink( NULL );
		
		// Перестать двигаться.
		SetAbsVelocity( vec3_origin );
 		SetMoveType( MOVETYPE_NONE );
		
		m_bActive = false;
	}
}

Здесь всё очень прямолинейно. Мы используем оператор if чтобы определить текущее состояние флага m_bActive. Знак восклицания означает "не": "Если m_bActive не равно true (истина), то сделать следующее...". Позже мы используем оператор else чтобы определить что мы будем делать в противоположном случае.

При активировании объекта мы начинаем его мыслительный процесс указывая движку Source какую мыслительную функцию использовать (по умолчанию это функция Think()(en), однако она у нас отсутствует). Отметьте наличие знака & и пробелов около каждой скобки в аргументе. Затем мы сообщаем движку, что наш объект будет перемещаться по миру летая, хотя это скорее не полёт а "плавание", т.к. в движке Source отсутствует имитация полёта (возможно вы сможете её добавить?). И, конечно, в конце мы устанавливаем m_bActive в true (истина) - само по себе это значение не поменяется!

После команды else мы останавливаем объект. Мы сбрасываем мыслительную функцию в ноль (NULL) чтобы остановить мыслительный процесс. Функция SetAbsVelocity()(en) устанавливает объект в его начало(en) - используется вектор с нулевой скоростью. Тип передвижения устанавливается в MOVETYPE_NONE(en), чтобы предотвратить любое перемещение, команда на которое может поступить извне. И в конце m_bActive устанавливается в false (ложь).

Запись FGD

Данная FGD запись позволяет Hammer'у отображать модель и позволяет вам задать имя объекта и послать ему входное сообщение "Toggle".

@PointClass base(Targetname) studio("models/gibs/airboat_broken_engine.mdl")= my_model_entity :  "Tutorial model entity."
[
	input Toggle(void) : "Toggle movement."
]

Работающий объект

my_model_entity в игре.

Поэкспериментируйте со своим объектом. Вы можете использовать консольную команду ent_fire my_model_entity toggle чтобы заставить его двигаться без вмешательства со стороны системы ввода/вывода карты. Вы можете отметить несколько особенностей:

Объект не сталкивается с другими физическими объектами.

Функции семейства SetAbs* не контактируют с физическими объектами. Если вы хотите симулировать физические столкновения вам придётся использовать другой метод перемещения.

Объект удаляется от меня каждый раз, когда я к нему подхожу.

Не совсем понятно почему это происходит. Возможно CBaseAnimating считает что путь объекта блокирован?

Смотрите также

• Полный код статьи(en)
• Ваш первый игровой объект(en)