Documentation/Programming Tutorials/Creation of an Entity Class

From NeoAxis 3D Engine Wiki

Jump to: navigation, search
Go to higher level

Contents

Introduction

In this tutorial you will learn to create game object classes. With this skill you will be able to create game objects of all types, dependent on your particular needs.

As an example you will create a game object changing its material when taking damage (e.g. when hit by a bullet).

This tutorial consists of two parts:

  • Creation of a game object class,
  • Creation of a game object type.

In the first part of the tutorial you will be creating a new game object class, while in the second part you will be creating a game object type (.type file) based on this class.

By the way, the object being created is already present in the SDK. So, you can just read this lesson without spending time on writing the code from the scratch. The source code is stored in the ExampleMagicObject.cs file of the GameEntities project. The type description files are stored in the Bin\Data\Types\Dynamic\ExampleMagicBall folder.

Creation of a game object class

Class creation

Now, proceed to the creation of a new class. Start the .sln file from the "Game\Src" folder. Open the GameEntities project and add a new file with the name: ExampleMagicObject.cs. Paste the following code to this file:

using System;
using System.Collections.Generic;
using System.Text;
using System.ComponentModel;
using System.Drawing.Design;
using Engine.MathEx;
using Engine.Renderer;
using Engine.MapSystem;
using Engine.PhysicsSystem;
 
namespace GameEntities
{
	public class ExampleMagicObjectType : DynamicType
	{
	}
 
	public class ExampleMagicObject : Dynamic
	{
		ExampleMagicObjectType _type = null; public new ExampleMagicObjectType Type { get { return _type; } }
	}
}

You can see that the code deals with two classes:

  • ExampleMagicObjectType - the class that will represent the game object type in the resource editor. This class is used for setting up parameters you will be able to adjust in the Object Type Editor.
  • ExampleMagicObject – the class of the object that will have copies in the game world. There will be one copy of each object on the map.

These classes are derived from the DynamicType and the Dynamic classes correspondently. The Dynamic class implements dynamic objects and is used as the basis for a large number of other classes. You will have touse it, since it has the OnDamage method (response to the damage dealt to the object).

Pay attention to the following line:

ExampleMagicObjectType _type = null; public new ExampleMagicObjectType Type { get { return _type; } }

It establishes a link between the game object type and the game code (i.e. links the two classes you have created). This code has to be included in any game object class.

Adding properties to the game type

Now, add a property to the game type that you will be able to edit in the game object editor.

public class ExampleMagicObjectType : DynamicType
{
	[FieldSerialize]
	string blinkMaterialName;
 
	/// <summary>
	/// Gets or sets the name of a replacing material.
	/// </summary>
	[Editor( typeof( EditorMaterialUITypeEditor ), typeof( UITypeEditor ) )]
	public string BlinkMaterialName
	{
		get { return blinkMaterialName; }
		set { blinkMaterialName = value; }
	}
}

The BlinkMaterialName property contains the name of the material to replace the old material when the object is hit by a bullet.

Pay attention to the line below.

[Editor( typeof( EditorMaterialUITypeEditor ), typeof( UITypeEditor ) )]

This line adds material choose dialog which can be opened by pressing "..." button.

The blinkMaterialName variable contains the file name, while [FieldSerialize] specifies that this property will be saved to a file when the game type is saved.

Writing class logic

Now proceed to the ExampleMagicObject class. Add the following variables to it:

MeshObject blinkMeshObject;
string originalMaterialName;

blinkMeshObject will contain object’s 3D model, while originalMaterialName will contain its original material.

The next step: add the OnPostCreate method (called on object creation) to your class.

/// <summary>Overridden from <see cref="Engine.EntitySystem.Entity.OnPostCreate(Boolean)"/>.</summary>
protected override void OnPostCreate( bool loaded )
{
	base.OnPostCreate( loaded );
 
	//To find the first attached mesh
	foreach( MapObjectAttachedObject attachedObject in AttachedObjects )
	{
		MapObjectAttachedMesh attachedMesh = attachedObject as MapObjectAttachedMesh;
		if( attachedMesh != null )
		{
			blinkMeshObject = attachedMesh.MeshObject;
			break;
		}
	}
 
	//To save the original name of a material
	if( blinkMeshObject != null )
		originalMaterialName = blinkMeshObject.SubObjects[ 0 ].MaterialName;
}

The first line calls the OnPostCreate parent method:

base.OnPostCreate( loaded );

Then, the mesh is found among the attached object and is written to the blinkMeshObject variable:

foreach( MapObjectAttachedObject attachedObject in AttachedObjects )
{
	MapObjectAttachedMesh attachedMesh = attachedObject as MapObjectAttachedMesh;
	if( attachedMesh != null )
	{
		blinkMeshObject = attachedMesh.MeshObject;
		break;
	}
}

Finally, the name of the mesh’s original material is written to the originalMaterialName variable:

if( blinkMeshObject != null )
	originalMaterialName = blinkMeshObject.SubObjects[ 0 ].MaterialName;

Now it is time to write a function that will change object’s material, if it is damaged. Object’s damage is implemented by the OnDamage method. You have to add it to your class:

//This method is called when the entity receives damage
protected override void OnDamage( MapObject prejudicial, Vec3 pos, Shape shape, float damage, bool allowMoveDamageToParent )
{
	base.OnDamage( prejudicial, pos, shape, damage, allowMoveDamageToParent );
 
	if( blinkMeshObject != null )
	{
		//To change a material
		if( blinkMeshObject.SubObjects[ 0 ].MaterialName == originalMaterialName )
			blinkMeshObject.SetMaterialNameForAllSubObjects( Type.BlinkMaterialName );
		else
			blinkMeshObject.SetMaterialNameForAllSubObjects( originalMaterialName );
	}
}

Here you can see, that first the parent method OnDamage is called:

base.OnDamage( prejudicial, pos, shape, damage, allowMoveDamageToParent );

Then, object’s material is changed. The original material will be changed to blinkMaterialName and blinkMaterialName will be changed to the original material:

if( blinkMeshObject.SubObjects[ 0 ].MaterialName == originalMaterialName )
	blinkMeshObject.SetMaterialNameForAllSubObjects( Type.BlinkMaterialName );
else
	blinkMeshObject.SetMaterialNameForAllSubObjects( originalMaterialName );

You have finished writing the code for your new game object.

Creation of a new game object type

Preparing resources

Material for the magical sphere
Physical model of the magical sphere

You can create and adjust game types in the Object Type Editor (a part of the Resource Editor).

Start the Resource Editor. Use the "Data\Types\Dynamic\ExampleMagicBall" folder to store your new game type.

Before creating a new game type you have to prepare all the necessary resources. You will need:

  • A mesh (in this case it should be an ordinary sphere),
  • A material to be applied to the mesh when the object takes damage,
  • A physical model (You can use sphere as physical model as well).

All these resources are available from the "Data\Types\Dynamic\ExampleMagicBall" folder.

Creation of a game object type

Now proceed to the game object type creation. Right-click on the ExampleMagicBall folder and select the New Resource option from the list.

Magic ball3.jpg

Now set the resource type to Entity Type and press the Continue button.

Magic ball4.jpg

Now specify the name for the new type: ExampleMagicBall, and its class: ExampleMagicObject (the one you have created). Press the Next button.

Magic ball5.jpg

Editing a game object type

Double-click on the ExampleMagicBall.type file that has appeared to enter the edit mode.

Here you have to adjust the mesh, the physical model and the “blink” material (the BlinkMaterialName property).

Start with mesh adjustment. Right-click on the work field and select the Mesh option in the Attach Object menu.

Magic ball6.jpg

Select the Ball.mesh file in the "Data\Types\Dynamic\Ball" folder.

Magic ball7.jpg

Now adjust the BlinkMaterialName property. Select the game object in the Objects list and press the "..." button of the BlinkMaterialName parameter.

Adding a blink material to an object

Select the already prepared ExampleMagicBallBlinkMaterial.highMaterial material from the current folder.

Magic ball9.jpg

Now you have to link a physical model to your game type. Set the PhysicsModel parameter value to ExampleMagicBall.physics. To make sure, that the physical model is appropriate select the Show Physics checkbox in the lower panel of the Game Objects Editor. The radiuses of the mesh sphere and the physical model sphere should be equal.

The magic sphere and its physical model

Finally, set the AllowEditorCreate property to True in order to enable object creation in Map Editor..

Now you can save and test the game object type you have created.

Testing

It is time to see your new game object type in action. Add the ExampleMagicBall object to any map you like. The object can be found in the "Types\Dynamic" directory of the types list.

The magical sphere on the map

Start the simulation mode. Take a Shotgun and test the magical sphere. That is how ExampleMagicBall looks before the shot:

The magical sphere before the shot

And that is how it looks just after the shot:

The magical sphere after the shot

Resume

This is the end of our tutorial. You have learned to create game object classes and to adjust the game types derived from them.

Game objects system containing all the game classes and game object types is a powerful tool for the creation of game logic in NeoAxis Engine.