View source for Ru/Authoring a Model Entity

{{LanguageBar}}
{{Source topicon}}

''Предполагается что вы прочли и полностью поняли статью {{L|Authoring a Logical Entity}}.''

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

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

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

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

 <span style="color:blue;">#include</span> <span style="color:brown;">"cbase.h"</span>
 
 <span style="color:blue;">class</span> CMyModelEntity : <span style="color:blue;">public</span> CBaseAnimating
 {
 <span style="color:blue;">public</span>:
 	DECLARE_CLASS( CMyModelEntity, CBaseAnimating );
 	DECLARE_DATADESC();
 
 	CMyModelEntity()
 	{
 		m_bActive = <span style="color:blue;">false</span>;
 	}
 
 	<span style="color:blue;">void</span> Spawn( <span style="color:blue;">void</span> );
 	<span style="color:blue;">void</span> Precache( <span style="color:blue;">void</span> );
 
 	<span style="color:blue;">void</span> MoveThink( <span style="color:blue;">void</span> );
 
 	<span style="color:green;">// Входная функция</span>
 	<span style="color:blue;">void</span> InputToggle( inputdata_t &inputData );
 
 <span style="color:blue;">private</span>:
 
 	<span style="color:blue;">bool</span>	m_bActive;
 	<span style="color:blue;">float</span>	m_flNextChangeTime;
 };

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

{{note|Наш ''объект'' не начнёт двигаться пока не получит соответствующую команду от <code>InputToggle()</code>. Заставить ''объект'' двигаться можно только вызовом функции <code>InputToggle()</code> (а не простой установкой значения <code>m_bActive</code> в единицу) - это станет неплохой практикой после того как вы прочтёте статью.}}

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

 LINK_ENTITY_TO_CLASS( my_model_entity, CMyModelEntity );
 
 <span style="color:green;">// Начало описания данных класса.</span>
 BEGIN_DATADESC( CMyModelEntity )
 	
 	<span style="color:green;">// Сохранение/загрузка состояния ''объекта''.</span>
 	DEFINE_FIELD( m_bActive, FIELD_BOOLEAN ),
 	DEFINE_FIELD( m_flNextChangeTime, FIELD_TIME ),
 
 	<span style="color:green;">// Присвоение нашей входной функции имя в Hammer'e.</span>
 	DEFINE_INPUTFUNC( FIELD_VOID, "Toggle", InputToggle ),
 
 	<span style="color:green;">// Объявление "мыслительной" (think) функции.</span>
 	DEFINE_THINKFUNC( MoveThink ),
 
 END_DATADESC()

Самое большое отличие от созданного нами ранее логического объекта в наличии макроса <code>DEFINE_THINKFUNC</code>, который даёт движку Source знать о, так называемой {{L|Think|"мыслительной"}} функции.

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

 <span style="color:green;">// Имя модели нашего объекта.</span>
 <span style="color:blue;">#define</span>	ENTITY_MODEL	<span style="color:brown;">"models/gibs/airboat_broken_engine.mdl"</span>

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

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

== Функция Precache() ==

Мы добрались до первой функции. Функция <code>{{L|Precache()}}</code> вызывается при появлении объекта на карте и гарантирует загрузку всего, что в ней перечислено до того как появится игрок (т.е. до того как он увидит мир и получит контроль над игрой). Смотрите {{L|Precaching Assets|рекомендации по прекэшированию}} для получения дополнительной информации.

Прекэширование получило отдельное имя потому что существуют другие типы "{{L|asynchronous|асинхронной}}" загрузки, которые могут выполняться ''после'' появления игрока.

 <span style="color:green;">//-----------------------------------------------------------------------------
 // Назначение: Прекэширование необходимых объекту ресурсов.
 //-----------------------------------------------------------------------------</span>
 <span style="color:blue;">void</span> CMyModelEntity::Precache( <span style="color:blue;">void</span> )
 {
 	PrecacheModel( ENTITY_MODEL );
 
 	BaseClass::Precache();
 }

Для данного ''объекта'' мы прекэшируем модель, которую будем использовать, а затем вызываем функцию прекэширования нашего базового класса (которая в случае класса <code>CBaseAnimating</code> обеспечивает загрузку системы частиц для огня, т.к. каждый объект с моделью в игре может загореться). Другие команды прекэширования: <code>{{L|PrecacheParticleSystem()}}</code> и <code>{{L|PrecacheScriptSound()}}</code>

== Функция Spawn() ==

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

 <span style="color:green;">//-----------------------------------------------------------------------------
 // Назначение: Настраивает начальное состояние объекта.
 //-----------------------------------------------------------------------------</span>
 <span style="color:blue;">void</span> CMyModelEntity::Spawn( <span style="color:blue;">void</span> )
 {
 	Precache();
 
 	SetModel( ENTITY_MODEL );
 	SetSolid( SOLID_BBOX );
 	UTIL_SetSize( <span style="color:blue;">this</span>, -Vector(20,20,20), Vector(20,20,20) );
 }

Сначала мы вызываем функцию <code>Precache()</code>, а затем идут вызовы различных функций класса <code>CBaseAnimating</code>. Функция <code>{{L|SetModel()}}</code> задаёт модель объекта. В скобках ей передаётся [[#Defining the model|определённый нами ранее]] путь к модели объекта. Функция <code>{{L|SetSolid()}}</code> требует более подробных разъяснений. Она определяет форму, которую наш объект будет использовать для проверки на столкновение с другими объектами. Использование формы самой модели было бы очень, очень {{L|expensive|дорогим}} по отношению к ресурсам компьютера, поэтому движок Source предлагает несколько компромиссов:

;<code>SOLID_NONE</code>
:"Прозрачный" (не твердый) объект.
;<code>SOLID_BBOX</code>
:Используется ориентированный по осям ограничивающий короб.
;<code>SOLID_BSP</code>
:Используется BSP-дерево для определения твёрдости (используется в {{L|brush|брашах}}).
;<code>SOLID_CUSTOM</code>
:''Объект'' использует свои собственные функции для проверки на столкновения.
;<code>SOLID_VPHYSICS</code>
:Для определения точных столкновений используется встроенная в модель {{L|collision model|модель столкновений}}.

Эти пункты выбираются на уровне движка и авторы модов не могут добавлять или менять их. Мы используем параметр <code>{{L|SOLID_BBOX}}</code>, который генерирует "{{L|bounding box|ограничивающий короб}}", размер которого движок определяет так, чтобы он охватывал всю модель. Более "дорогой" параметр <code>{{L|SOLID_VPHYSICS}}</code>, который использует встроенную в модель {{L|collision model|модель столкновений}}, не поддерживает низкоуровневые функции перемещения, которые мы будем использовать для нашего объекта, поэтому мы его не применяем.

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

{{warning|<code>Spawn()</code> вызывается '''незамедлительно''' после создания объекта. Если это случится сразу же после создания карты нет гарантии того, что на карте уже появились другие объекты. Поэтому любой код, который предполагает что объект будет связываться с другими игровыми объектами становится ненадежным. В таких случаях используйте функцию <code>{{L|Activate()}}</code>, которая всегда вызывается после появления всех объектов.}}

== Функция MoveThink() ==

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

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

 <span style="color:green;">//-----------------------------------------------------------------------------
 // Назначение: Мыслительная функция для случайного перемещения объекта по карте.
 //-----------------------------------------------------------------------------</span>
 <span style="color:blue;">void</span> CMyModelEntity::MoveThink( <span style="color:blue;">void</span> )
 {
 	<span style="color:green;">// Смотрим, должны ли мы снова поменять направление.</span>
 	<span style="color:blue;">if</span> ( m_flNextChangeTime < gpGlobals->curtime )
 	{
 		<span style="color:green;">// Задаём случайное направление и скорость.</span>
 		Vector vecNewVelocity = RandomVector( -64.0f, 64.0f );
 		SetAbsVelocity( vecNewVelocity );
 
 		<span style="color:green;">// Сменить направление снова через 1-3 секунды.</span>
 		m_flNextChangeTime = gpGlobals->curtime + random->RandomFloat( 1.0f, 3.0f );
 	}
 
 	<span style="color:green;">// Поворот объекта туда, куда идет движение.</span>
 	Vector velFacing = GetAbsVelocity();
 	QAngle angFacing;
 	VectorAngles( velFacing, angFacing );
  	SetAbsAngles( angFacing );
 
 	<span style="color:green;">// Запускать эту функцию с частотой 20Hz</span>
 	SetNextThink( gpGlobals->curtime + 0.05f );
 }

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

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

*<code>{{L|gpGlobals}}->curtime</code> возвращает время, в которое исполняется текущий код, как значение с плавающей точкой.
*<code>[[Wikipedia:Vector (spatial)|Вектор]]</code> - это набор переменных, используемых для определения движения, которые содержат в себе данные о направлении и скорости. Функция <code>{{L|SetAbsVelocity()}}</code> задаёт абсолютную скорость, 
*<code>{{L|QAngle}}</code> это просто угол - т.е. то же самое что вектор только без данных о скорости. <code>{{L|QAngle}}</code> задаёт направление.
*Функция <code>{{L|VectorAngles()}}</code> преобразует вектор (<code>velFacing</code>) в угол (<code>angFacing</code>). Не забывайте, что С++ очень строг в отношении типов: вам понадобятся утилитарные функции, такие как <code>VectorAngles()</code>, чтобы осуществлять преобразования между двумя типами.

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

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

{{tip|На самом деле нам не очень то и нужна переменная <code>vecNewVelocity</code>. Попробуйте передать значение в функцию <code>SetAbsVelocity()</code> без создания лишней переменной. Вспомните почему мы добавляем <code>void</code> перед всеми нашими функциями.}}

== InputToggle() ==

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

 <span style="color:green;">//-----------------------------------------------------------------------------
 // Назначение: Включать/выключать движение объекта.
 //-----------------------------------------------------------------------------</span>
 <span style="color:blue;">void</span> CMyModelEntity::InputToggle( inputdata_t &inputData )
 {
 	<span style="color:green;">// Переключение состояния активности.</span>
 	<span style="color:blue;">if</span> ( !m_bActive )
 	{
 		<span style="color:green;">// Начало мыслительного процесса.</span>
 		SetThink( &CMyModelEntity::MoveThink );
 
 		SetNextThink( gpGlobals->curtime + 0.05f );
 		
 		<span style="color:green;">// Начать летать.</span>
 		SetMoveType( MOVETYPE_FLY );
 
 		<span style="color:green;">// Установка времени для смены направления и скорости.</span>
 		m_flNextChangeTime = gpGlobals->curtime;
 
 		<span style="color:green;">// Изменение переменной m_bActive для отображения текущего состояния.</span>
 		m_bActive = <span style="color:blue;">true</span>;
 	}
 	<span style="color:blue;">else</span>
 	{
 		<span style="color:green;">// Перестать мыслить.</span>
 		SetThink( NULL );
 		
 		<span style="color:green;">// Перестать двигаться.</span>
 		SetAbsVelocity( vec3_origin );
  		SetMoveType( MOVETYPE_NONE );
 		
 		m_bActive = <span style="color:blue;">false</span>;
 	}
 }

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

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

После команды <code>else</code> мы останавливаем объект. Мы сбрасываем мыслительную функцию в ноль (<code>NULL</code>) чтобы остановить мыслительный процесс. Функция <code>{{L|SetAbsVelocity()}}</code> устанавливает объект в его {{L|origin|начало}} - используется вектор с нулевой скоростью. Тип передвижения устанавливается в <code>{{L|MOVETYPE_NONE}}</code>, чтобы предотвратить любое перемещение, команда на которое может поступить извне. И в конце <code>m_bActive</code> устанавливается в 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."
 ]

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

[[File:My model entity.jpg|thumb|my_model_entity в игре.]]

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

;Объект не сталкивается с другими физическими объектами.
:Функции семейства <code>SetAbs*</code> не контактируют с физическими объектами. Если вы хотите симулировать физические столкновения вам придётся использовать другой метод перемещения.
;Объект удаляется от меня каждый раз, когда я к нему подхожу.
:Не совсем понятно почему это происходит. Возможно <code>CBaseAnimating</code> считает что путь объекта блокирован?

== Смотрите также ==
* {{L|Authoring a Model Entity/Code|Полный код статьи}}
* {{L|Your First Entity|Ваш первый игровой объект}}

{{ACategory|Programming}}
{{ACategory|Tutorials}}