Programming Manual

Overview

Intended Audience for Manual

Though examples may be provided in C#, it applies to any .NET programming language, including Visual Basic and C++/CLI, and to a degree, to IronPython scripting as well.

This documentation is primarily written for programmers and more technical scripters, but also describes major new concepts for the new way of defining Entities through toolset (instead of via code) which is one of the primary features of the v0.9.9 release.

Topics Covered

This focuses on the new types of components which can be assembled and configured through the toolset to define Entities (such as Characters, Vehicles, Avatars), Smart Objects (or Doors, Weapons, Equipment, and other Items), focusing on how to define new components (eg. Abilities, Behaviors, Actions/Commands, Events, and Entity types) which can be used by non-programmers to setup and configure new entitys (as reusable assets / prefabs shown in Asset Explorer, able to be drag-dropped into the scene, for example) as well as how to define gameplay / mission / scenario scripting (for instances of those entity assets placed into scenes, for example) through Triggers (Scriptable Persisted Events, replacing old Command Mapping way of doing this), Triggered Areas (Proximity Triggers), Behavior Trees, and Key Mappings.

It also covers how to edit Key Mappings (for the Global Key Map, or Entity type-specific Key Mappings defined with the Input Controller presets) and how to map animations and behaviors to those Key Mappings (via Entity Triggers which map scripted action(s) to command names or events, such as EntityKeyEvent's).

Hooking up Gameplay in Scenes (and Creating Entity, Scenario, Ability and Action Component Classes) (NEW!)

This tutorial is the first in the sequence showing how to create the new Isles of War demo game included with Visual3D from start to finish using the new visual authoring tools available in the latest release of the Visual3D All-in-One toolset. This segment specifically covers how to add gameplay, such as for a Capture the Flag (CTF) mission, to a scene, how to create your own custom component classes (such as for Scenario, Entity, Ability and Action, in C# or any other .NET language) and have them automatically appear assets for use in the toolset. It also covers how to use Visual Studio's edit-and-continue and debugging tools side-by-side while editing and running your game or simulation in the Visual3D toolset.

Key Base Classes for v0.9.7+

Ability (derives from BehaviorBase / ComponentBase)
ActionBase (derives from Command)
ObjectBehavior (implements IActivated)
BaseEvent (and more commonly used BaseSelf(Target)Event derived classes)
ComponentBase (and EntityComponent, for "data objects")
1. Currently EntityComponent (which implements IComponentBase2 interface) is required for full component functionality (Name, Prefab/Prototype Asset Linking, etc.), however, EntityComponent will soon be fully merged into ComponentBase.
EventBase (base class for BaseEvent, derived from EventArgs, used for non-scriptable events)
1. Often BaseEvent is used instead, as is currently required for scriptable events (which work with Triggers, Behavior Trees, etc.)
2. BaseSelfEvent event, which defines the "Self" (Actor/Entity/Owner) parameter (as well as BaseSelfTargetEvent, which defines both Self and Target parameters) are most common base classes used for events, they derive from BaseScript, to allow use as scriptable events
Trigger (for "Entity Triggers" represented persisted, toolset-defined scriptable events or command ID mappings)
1. Triggers with IsCommand = true (or CommandName set, or TriggerType set to Command, as this may change in near feature) will be used to define persisted command ID mappings, a toolset-defined/persisted/editable alternative to older hard-coded mapping of commands and animations to command ID's (or Key Map Event ID's).
2. Usually Triggers should be created for an Entity (or SceneObject) asset (prototype/prefab/preset) defined in Asset Explorer, which is then placed (instanced) into scenes, instead of defined via code. However, some abilities will automatically add new triggers to their owner entity, when they are attached to an entity, which part of how they expose scriptable events or new actions that they extent that entity with.

Creating Your Own Entity Assets and Classes

You can create a copy of one of the existing Entity assets / Prefabs, for example, by selecting "F-38" or "Lizardman" under Entities folder in Asset Explorer, then right clicking it and selecting "Create Derived Copy", renaming it, and customizing it in Object Editor (and Entity/Model Editor) and drag-dropping it into a scene.
You can also right click on a folder in Asset Explorer like Entities and select > Add New (or click on the "+" icon in Asset Explorer toolbar) and select one of the more common Entity classes (or your own common prefabs/presets if you drag-drop them into the Base Types group in Asset Explorer).

You can also create a new Avatar class by creating a copy of one of the sample entity classes (as listed below in Example Classes for Entities section) and adding it to your own Visual Studio project (such as the .csproj generated for you by Visual3D in your world project folder when creating a new world). For example, you can copy the file found at \Demo Assets\Actors\Custom\F38Jet.cs, renaming it to something like Aircraft.cs, renaming the class to something like Aircraft, apply the ComponentTypeAttribute to ensure it will get automatically added as an Entity asset to Visual3D, such as by applying [ComponentType("Entities", "Vehicles")] and [DataContract] (if not already defined) to the class. (For your most common entity or component classes, you can apply [AssetBaseType] attribute as well to them, to have them automatically added to Base Types asset group, to show up in the Add New > context menu.)

Then, when you next startup Visual3D Architect, it should show up in Asset Explorer (in this example, under Entities/Vehicles). You can find it there and select it to continue configuring it, and setting up/selecting a model for it.

You could then select your avatar/entity prefab asset (which, for example, you had created through right click > Create Derived Copy in Asset Explorer or which was auto-created for your own custom class defined in, for example, C# code, which had [ComponentType] and [DataContract] attributes applied to it).
After selecting the asset, go to Object Editor and change its model by clicking on "..." for the Model property and selecting your model from the Model Selector dialog shown.

You can configure other properties shown in Object Editor for it, as well as attach Abilities and other components or child objects to it (eg. via Add New, Add Asset, or other context menu options shown when right clicking your asset in Asset Explorer) and can preview and further configure it by double clicking on your asset and previewing it in Entity Editor (Entities > Entity tab), and editing the shared settings for its Model (Physics, etc.) through Model Editor (Entities > Model tab).

One of common properties to edit for it is the Object Type (or Physical Entity Class) property, for example to change it from being an Obstacle to being a Character or Vehicle or Scripted Movement Object or Moveable (Physics-controlled / Dynamic) Object. In v0.9.7, this and a few other common properties are shown in a dialog the first time you try to drag-drop a new Model into the scene.

Sample Classes for Avatars and Other Entities

Much of the need for custom coding in C# as seen in these example classes has been removed for the upcoming v0.9.7 release, through the use of modular "Abilities" (InventorySupport, Combatant, Mobile, etc.) which can be drag-dropped onto any SceneObject / Entity (whether a prefab asset or instance in the scene) instead of having to hook these up via code.

Also, for v0.9.7+, new Entity classes (for Characters, Vehicles, and other Avatars as well as Weapons and other items) should be derived from the new AvatarBase or EntityBase base classes instead of derived from Avatar, Actor, or SceneObject. However, many of those classes will not have been replaced / rewritten yet when the v0.9.7 release is made, and some of this logic will be kept anyways to serve as useful reference on how to do setup similar functionality via code instead of through the toolset.

Aircraft
- F38Jet - Jet aircraft
- For humanoid with jet pack and gunfire - FlyingDroid
- FlyingAvatar base class
Humanoid Combatant (with AI and User Controllable)
- Melee / Hand-to-Hand Combat - Lizardman
- Ranged / Gunfire Combat - AssaultDroid2 (AssaultDroid class is the somewhat overcomplicated version for pre-blended animations)
NPC with Dialogue (and Basic Hand-to-hand Combat)
- CasualHumanMaleAvatar
- CasualHumanAvatar base class
Land Vehicle
- DesertPatrolVehicle
- BaseVehicle base class
Watercraft / Boat / Ship
- GalleonShip
Flocks / Swarms / Packs of Multiple Entities
- Group of Animated Avatar (Creatures / NPCs / Enemies) with Flocking AI: LizardmanFlock
- Particle System-based (Visual Effect)-based: FlockOfSeagulls, SchoolOfFish
  - (Particle systems can be defined using Particle Editor now, and drag-dropped onto any Prefab / SceneObject asset now, to reduce or avoid need for coding like in these examples)
Other Avatars and NPCs
- Avatar base class (which all above classes are derived from). This is derived indirectly from Actor and SceneObject.
- AvatarBase (new in v0.9.8)
  - This will end up replacing the Avatar base class (which most Avatar classes are currently derived from). It is a new lightweight ability component designed as a base class for user-defined characters/avatars, weapons, items, and other game objects.
  - Use of this base class allows any SceneObject to be made into a certain game object type through the toolset, even after that SceneObject is created. It also allows for delayed creation of SceneObject's, which is useful for Inventory Items, for example.
  - (which is not derived from SceneObject) is the new base class for user-defined Avatar classes in upcoming v0.9.6
Weapons
- Gun / Ranged Weapon - MissileLauncher
- Projectiles / Ammo
  - Gun / Ranged Weapon -
  - MissileWeapon and derived classes (Rocket, Bullet, Laser, Meteor, WaterBall)
- Weapon base class
Inventory Items and Other Objects
- Descructible and StandardActor
- EntityBase (new in v0.9.7)
  - The more general purpose/lightweight base class for AvatarBase
  - This will replace Descructible, StandardActor, Actor and SceneObject as the new suggested base class for Weapons and other objects/items

Abilities: Extending Entity Capabilities
Abilities are components which can be attached to any Entity (EntityBase or SceneObject "component owner") through the toolset.
Ability is derived from BehaviorBase, which is a common base class for components which can be "activated" and attached to an entity (or SceneObject) owner, and which can, optionally (if their UpdateInterval property is set) be updated at a pre-defined frequency (which is scaled and paused with game time, by default).

Class Hiearchy

        Ability (in Visual3D.Scripting.Behaviors)
          AnimationSet (in Visual3D.Graphics3D.Animations)
          BehaviorSystem (in Visual3D.Scripting.Behaviors)
            AStarNavigator (in Visual3D.Demo.AI)
            Combatant (in Visual3D.Demo)
              CTFCombatant (in Visual3D.Demo)
            Mobile (in Visual3D.Scripting.Behaviors)
            Navigator (in Visual3D.Scripting.Behaviors)
            Speaker (in Visual3D.Scripting.Behaviors)
          DialogSupport (in Visual3D.Scripting.Dialog)
          ExplosionSupport (in Visual3D.Demo.Actors)
          GameParameters (in Visual3D.Demo.Actors)
          Inventory (in Visual3D.Demo.Actors)
          MapMarkSupport (in Visual3D.Demo.Actors)
          Perception (in Visual3D.Scripting.PerceptionSystem)
          StackBehaviorController (in Visual3D.Scripting.Behaviors)

Behaviors: Long-running Scripts

This section describes Behaviors, which are basically which are often defined in C# (or another .NET language like Visual Basic or C++/CLI) or Python (IronPython).
Unlike Actions (aka. Commands) can be long-running, as they have an IsActive state, and which can be updated. They are usually not attached directly as components to an entity, but are instead started or stopped via Actions attached to Triggers, or via Behavior Trees, or via other scripts.

Class Hierarchy

        ObjectBehavior (in Visual3D.Scripting.Behaviors)
          ActivateConstraint (in Visual3D.Scripting.Behaviors)
          Animate (in Visual3D.Scripting.Behaviors)
          AnimateCS (in Visual3D.Scripting.Behaviors)
          Attack (in Visual3D.Demo.Scripting.Behaviors)
          BehaviorTree (in Visual3D.Scripting.Behaviors)
          CompositeBehavior (in Visual3D.Scripting.Behaviors)
            ActivityBehavior (in Visual3D.Scripting.Behaviors)
              WorkflowBehavior (in Visual3D.Scripting.Behaviors)
            ScriptBehavior (in Visual3D.Scripting.Behaviors)
          Move (in Visual3D.Scripting.Behaviors)
          Navigate (in Visual3D.Scripting.Behaviors)
          OpenDoor (in Visual3D.Scripting.Behaviors)
          ParallelBehavior (in Visual3D.Scripting.Behaviors)
          PhysicsDrag (in Visual3D.Scripting.Behaviors)
          Rotate (in Visual3D.Scripting.Behaviors)
          RotateOnAxis (in Visual3D.Scripting.Behaviors)
          StopCurrentBehavior (in Visual3D.Scripting.Behaviors)
          Talk (in Visual3D.Scripting.Behaviors)
          Translate (in Visual3D.Scripting.Behaviors)
          Turn (in Visual3D.Scripting.Behaviors)
          WaitFor (in Visual3D.Scripting.Behaviors)

Actions: Instant Commands (C# Scripts) for Triggering Behaviors

This section describes Actions (aka. Commands) are Instant Scripts Defined in C#, which can often to used to start a Behavior (long-running script defined in C# or Python, aka. Activity).

Class Hierarchy

    ICommand (in Visual3D)
      Command (in Visual3D)
        ActionBase (in Visual3D.Scripting.Actions)
          AttachViaPhysicsConstraint (in Visual3D.Scripting.Actions)
          CreateEntity (in Visual3D.Scripting.Actions)
          PlayCinematic (in Visual3D.Scripting.Actions)
          PlaySound (in Visual3D.Scripting.Actions)
        ExecuteTriggeredCommand (in Visual3D.Commands)
        PrimitiveCommand (in Visual3D)
          BatchStartCommand (in Visual3D.Commands)
          BatchStopCommand (in Visual3D.Commands)
          ExecuteCommand (in Visual3D.Commands)
          MethodCommand<T> (in Visual3D.Commands)
          MethodCommand (in Visual3D.Commands)
          SimpleMethodCommand (in Visual3D.Commands)
          StartAction (in Visual3D.Scripting.Triggers)
          StartAnimationCommand (in Visual3D.Graphics3D.Animations)
          StartBehavior (in Visual3D.Scripting.Triggers)
          StartCommand (in Visual3D.Commands)
          ToggleActivationCommand (in Visual3D.Commands)
          TriggerBehaviorSystem (in Visual3D.Scripting.Triggers)

Triggers and Key/Event Mapping

This section covers mMapping Actions, Behaviors, and Animations to Keys and Events

Entity Triggers

Triggers or "Entity Triggers" are scriptable events that can be defined on any entity through the toolset. They are named components which define a list of Actions (or Commands) which are executed when the Trigger is executed.

Triggers are executed when either their Event (defined via their Event property) condition occurs, or (under development) or when attempting to execute a command mapped to the Trigger's name, if the IsCommand property of the Trigger is set to true. Commands were previously defined for things like "MoveForward", "Attack", "Idle" (or "OnIdle"), "LaunchMissile", etc. through hard-coded command to name mapping occurring in OnConstructPrototype() method of Avatar (and SceneObject or Actor) derived classes, however, these should now be defined through the toolset instead.

Trigger (for "Entity Triggers" represented persisted, toolset-defined scriptable events or command ID mappings)

Triggers with IsCommand = true (or CommandName set, or TriggerType set to Command, as this may change in near feature) will be used to define persisted command ID mappings, a toolset-defined/persisted/editable alternative to older hard-coded mapping of commands and animations to command ID's (or Key Map Event ID's).
Usually Triggers should be created for an Entity (or SceneObject) asset (prototype/prefab/preset) defined in Asset Explorer, which is then placed (instanced) into scenes, instead of defined via code. However, some abilities will automatically add new triggers to their owner entity, when they are attached to an entity, which part of how they expose scriptable events or new actions that they extent that entity with.

Class Hierarchy

Trigger (in Visual3D.Scripting.Triggers) derived from EntityComponent

Key Mapping

Whenever a Key Mapping (defined in the "Global Key Map" which can be seen in World Explorer and edited via Object Editor) event occurs (eg. the "W" key being pressed results in "MoveForward" key mapped event occuring) a Command (or Trigger with IsCommand=true) with that name (eg. "MoveForward") will be automatically executed on the current Avatar (or Focused SceneObject/Entity, such as the Camera if no Avatar is defined).
Entity-specific key mapping found at InputController.KeyMap for any SceneObject, and only apply when a SceneObject using that same InputController (as are often defined as preset/shared assets) is focused.

Events

EventBase (base class for BaseEvent, derived from EventArgs, used for non-scriptable events)

Often BaseEvent is used instead, as is currently required for scriptable events (which work with Triggers, Behavior Trees, etc.)
BaseSelfEvent event, which defines the "Self" (Actor/Entity/Owner) parameter (as well as BaseSelfTargetEvent, which defines both Self and Target parameters) are most common base classes used for events, they derive from BaseScript, to allow use as scriptable events

Trigger Area (aka. Proximity Sensors)

Trigger Area's (instances of the TriggeredArea class) are one type of Entity (or SceneObject) which can be placed entity scenes. These entities define different Entity Triggers for different events, such as entering, exiting, or remaining inside of (within a certain update interval) the area defined for th Triggered Area, allowing scripted actions (including Triggering Events or Entity Triggers on other entities, such as the entity entering or leaving a trigger area).

Entities, Actors, and Smart Objects

Entities

It is now suggested to derive from EntityBase instead of SceneObject or Actor, and to derive from AvatarBase instead of Avatar, since these are the base classes for user-defined scriptable entities which "have" or "own" a SceneObject (eg. an Actor) for their appearance, a SpatialNode for their position, and a PhysicalEntity / ObjectPhysics for their physics/collision support, as well as other components (or abilities) which are now decoupled (more modular) so that they can be more easily used if/when needed, or added to any SceneObject in the scene entire through the toolset.

Class Hierarchy

IAgent (in Visual3D)
    IEntity (in Visual3D)
      EntityBase (in Visual3D)
        AvatarBase (in Visual3D.Demo)

Scene Objects

SceneObject (as well as Actor and Avatar) are common base classes to allow customized rendering (appearance or low-level engine / scene graph support), though they had been used previously as base classes for user-defined Avatar (Character and Vehicle) and Item (Weapon and Equipment) and Object (Door, Elevator, Chest/Container, etc.) as well, it is now suggested that such user-defined "entity" or "item" classes derive from EntityBase (or AvatarBase) class instead of SceneObject, Actor or Avatar.

In some cases it may still be neccisary to define a class derived from SceneObject, Actor or Avatar. However, in those cases, it is suggested that a new EntityBase-derived class (which is tightly coupled / mapped 1-to-1 with the new SceneObject-derived class) should often be defined. Most of the editable and persisted or high-level (eg. game/application-specific) properties and logic defined on the EntityBase-derived class instead. We will be reducing the number of cases in which users need to derive from SceneObject, Actor or Avatar base class at all.

Class Hierarchy

SceneObject (in Visual3D)
Actor (in Visual3D.Demo)

Avatar (in Visual3D.Demo)

          OgreMaxSceneAsset (in Visual3D.Assets.Loaders.OgreScene)
          PathPointObject (in Visual3D.Scripting.PathSystem)
          PhysicalHullAsset (in Visual3D.Demo)

Low-level Components and Data Objects

ComponentBase and EntityComponent: For Persistant Data Objects and Entity-Owned/Attached Components

ComponentBase is the primary, lowest-level base class shared between many different class heirarchies.

Currently, some of its core functionality (such as support for naming and linking to base asset (aka. prototype/prefab/preset) an instance was created from - are only defined in the derived EntityComponent class. We intend to merge the EntityComponent class into the ComponentBase class, removing some of the legacy (old, often unused) members of EntityComponent like UniqueName, however you can derive from EntityComponent in the mean time and should be able to switch over fairly easily once these classes have been merged.

ComponentBase can be thought of as a "Data Object" as much of what it handles relates to persistance (serialization, persisted references, smart copy "instancing", etc.). However, it has also adds support for new, under-development service model (looking up services) and event mapping. It also has some functionality previously only available to SceneObjects (and other Entity-derived classes like Scene and GuiForm), such as the ability to "own" other components, however, it only provides low-level support for this, and you should derive from EntityBase (or, in some rare cases, from SceneObject or Actor as well) to ensure that most components are able to be attached to your component class instance (for example, via drag-drop or the right click > "Add New" or > "Add Asset" or other Add/Attach ... context menu options) and to ensure that many scripting tools and features work with your class.

Currently many scripting features, such as ObjectBehavior's, Script Events, Behavior Trees, and (to a degree) Entity Triggers, require an EntityBase-derived class which owns a SceneObject (exposed via the EntityBase.VisualObject property) to provide full scripting support.

BehaviorBase: For Activateable (Startable/Stoppable) and (Optionally) Updated Components

BehaviorBase is the base class for Ability. Similar to ObjectBehavior, this class is used for things which need to have an "Active" state (via its implementation of IsActive, Activate(), and Deactivate() defined on the IActivated interface), however, unlike ObjectBehavior, this class is not intended as a lightweight temporary activity/state which is recreated each time a behavior is started. Instead, it derived from EntityComponent (and therefore ComponentBase), and is intended to be attached directly to any Entity or SceneObject. Custom update logic can be defined for classes deriving from BehaviorBase by overriding OnUpdated() and ensuruing that the UpdateInterval is set to an update time (or frequency) other than 0 (which is currently the default, to prevent updating behaviors which don't require it).

The ComponentTypeKey property can be set to (or overriden to always return) a the component classes type (or base type), to allow looking up a behavior by its type, which is usually done if want to ensure that there is only one behavior a specific type defined for an entity at a time (though in some cases, this can be supported without preventing additional secondary instances of a behavior class).
IsAutoActivated can be set to true to ensure that a behavior component is always activated when its own is activated, by default, though behaviors can be deactivated later manually, still, even when auto-activation is enabled.

By default, BehaviorBase (and derived classes like Ability) are updated based on "Scene (aka. Game/Simulation) Time", meaning they are paused (not updated, as they still remain "Active") when the game/simulation/scene is paused, and are updated more often when game time is "sped up" or "slowed down".

Reference for Toolset Developers

This section is primarily for advanced use by toolset and engine developers, or advanced reference use by those customizing or extending the toolset.

Script Definition Assets

This section describes legacy classes or classes used to define shared script definitions, but which should almost never be used directly by users. ObjectBehavior, Abiltity (or BehaviorBase or BehaviorSystem), ActionBase (or Command) derived classes should be used instead, such as ScriptBehavior or BehaviorTree or Trigger.

Class Hierarchy

Script (in Visual3D.Scripting)

          BTScript (in Visual3D.Scripting)
            BTBehaviorScript (in Visual3D.Scripting)
          TextScript (in Visual3D.Scripting)
            PythonScript (in Visual3D.Scripting)
              PythonActionScript (in Visual3D.Scripting)
              PythonBehaviorScript (in Visual3D.Scripting)
              PythonModuleScript (in Visual3D.Scripting)
          VisualScript (in Visual3D.Scripting)
            VisualActionScript (in Visual3D.Scripting)
            VisualBehaviorScript (in Visual3D.Scripting)

Conceptual Hierarchy (Key Interfaces and Implementing Classes)

You can find conceptual hierarchy of main base classes and interfaces by looking at the ISimComponent interface and all types derived from it. This interface and class hierarchy can be viewed by using ReSharper > Explorer Class Hierarchy, .NET Reflector > expanding "Derived Types" under interface, looking at generated API documentation, for example).

Additional Information

Additional information can be found in the Asset Management (Explorer, Pipeline, and Database) user manual describing how to work with the Asset Database and write persisted component classes which are automatically added to, or persisted through, the Asset Database, and viewed/used/edited through the Asset Explorer, as well as how this relates to Asset Pipeline for importing/exporting media assets (eg. models) and saving edits made. The Asset Management manual does show a number of screenshots for how to use Asset Explorer, however, it is somewhat outdated, and information describes in this Programming User manual is currently more up-to-date in places.
We plan on providing separate manual and video tutorial covering use of Asset Explorer, and have other documentation (including video tutorials) covering importing, exporting, and Entity/Model Editor use under our Asset Creation user manual.

User login

Free Download

Visual3D Game Engine v.9.9.1

Documentation Wiki

Search

Game Engine Manuals

Navigation