Torque3D
  • General
    • Welcome!
    • Features
    • Release Notes
      • Version 4.0.3
      • Version 4.0.2
      • Version 4.0.1
      • Version 4.0
      • Version 3.10.1
      • Version 3.10
      • Version 3.9
      • Version 3.8
      • Version 3.7
      • Version 3.6.2
      • Version 3.6.1
      • Version 3.6
  • Getting Started
    • Introduction
      • What's the Torque3D Engine?
    • Getting Familiar
      • Getting a Copy
        • Torque Project Manager
        • Downloading it Yourself
      • Getting Ready for Launch
        • Running Pre-Built Binaries
        • Building the Engine Yourself
      • Launching the Game
        • Opening the Example Level
        • Launching the Editors
      • Your First Game
        • Introduction To The Engine
        • The Module System
        • Creating an empty gamemode
        • Adding a Player
        • Adding a Coin
        • Adding a win-condition
        • Custom coin asset
        • Counting coins
        • Adding some effects
        • Supporting multiplayer
        • Adding a Scoreboard GUI
        • Keeping the scoreboard up-to-date
      • Deep Dive: BaseGame Directory Structure
    • Best Practices
    • Porting a Legacy Project
  • For Artists
    • Assets
      • What are Assets?
      • How to Create a New Asset
      • Working With Assets
      • Deep Dive: Creating a New Asset Type
    • Art
      • File Formats
      • 3D Art
        • Shape Specifications
        • Coordinates System
        • Mounting Shapes
        • Animation
        • Player Setup
        • Blender -> Torque3D Pipeline
      • 2D Art
        • Working with Adobe Substance
    • Animation
    • GUI
      • Loading and Initializing a GUI
      • Expanding a GUI via Script
      • How to Network GUIs
    • Materials
      • Material Mapping
      • Material Animation
    • Terrain
    • Shaders
    • Lighting
    • Audio
  • For Designers
    • Base Classes
      • SimObject
      • SimGroup
      • SceneObject
      • Scene
      • Datablocks
    • Game Classes
      • Creating an Object
      • Destroying an Object
      • Gameplay Scripting
        • Spawning an Object from Gameplay Code
    • Modules
      • What are Modules?
      • How to Create a New Module?
      • Making a Module do Things
      • Installing Existing Modules
        • Where to Get More Modules
    • Scenes and Levels
      • How to Create a New Level
      • How to Load a Level
        • Deep Dive: Level Loading Scripts
      • How to Edit Levels
        • Opening a Level in the Editor
        • Spawning Objects from the Asset Browser
        • Working with Scenes
        • Using SimGroups
        • Changing a Level's PostEffects
        • Deep Dive: LevelAsset Companion Files
    • Game Modes
      • Creating a New GameMode
      • Making a Level Use Your GameMode
      • Adding Gameplay Code to Your GameMode
    • AI
      • Navmesh
      • Objects
      • Scripting
    • Inputs
      • Inputs and Keybinds
        • ActionMap
        • Bind Functions
        • ActionMap Stack
    • Localization
    • Editors
      • Changing Editor Settings
      • World Editor
        • Scene Editor
        • ConvexShape Editor
        • Terrain Editor
        • Terrain Painter
        • Material Editor
        • Spline-Based Tools
          • Mesh Road Editor
          • River Editor
          • Decal Road Editor
        • Datablock Editor
        • Particle Editor
        • Decal Editor
        • Forest Editor
        • Navmesh Editor
        • Deep Dive: Creating Your Own Editor
        • Shape Editor
      • GUI Editor
        • Interface Details
  • For Programmers
    • Compiling the Engine
      • Setup Development Environment
        • SDK and Library Installation
        • Git
        • Cmake
        • Creating a Fork on Github
      • Create a Project
        • Creating a Project With CMake
        • Creating a Project With the Project Manager
      • Compiling
        • Compiling in Windows
        • Compiling in Linux
        • Compiling in MacOS
      • Building the Project Manager
    • Introduction
    • Code Style Guidelines
    • Expanding the Engine
      • Creating a New Object Class
      • Exposing Object Classes to Script
        • addProtectedField
      • Adding a New Library to the Engine
    • Major Components of the Engine
      • Core
        • Console
        • Platform
      • Audio
        • SFX
      • Rendering
        • GFX
        • Render Bins
      • Physics
        • Stock T3D Physics
        • Physics Wrapper
          • PhysX
          • Bullet
        • Classes
    • Rendering
    • Math
    • Networking
      • Client and Server Commands
    • Physics
    • Collision
    • Scripting
      • TorqueScript
        • What is TorqueScript?
        • Basic Syntax
        • Variables
        • Types
        • Operators
        • Control Structures
        • Functions
        • Objects
        • Module Interop
          • QueueExec
          • RegisterDatablock
          • CallOnModules
          • ModuleExec
        • API Reference
      • Other Languages
        • C-Interface
    • File Inputs/Outputs(I/O)
    • API Reference
Powered by GitBook
On this page
Edit on GitHub
Export as PDF
  1. For Programmers
  2. Expanding the Engine
  3. Exposing Object Classes to Script

addProtectedField

Using addProtectedField

The addProtectedField function is used to define a new field for an object class, which can be accessed and modified in scripts and in the engine's GUI editor. The main difference between addField and addProtectedField is the latter controls access of the class object's variable. The basic syntax for using addProtectedField is as follows:

addProtectedField( name, type, offset(className, fieldName), setFunction, getFunction, writeFunction, description );

where:

  • name is the name of the field as it will appear in the editor, or used in scripts.

  • type is the data type of the field, such as TypeS32, TypeF32, TypeString, etc.

  • fieldName is the name of the class' attribute variable being exposed.

  • className is the name of the class the field is being exposed for.

  • setFunction is the name of a custom set function that is called whenever the value of the field changes.

  • getFunction is the name of a custom get function that is called whenever the value of the field is accessed.

  • writeFunction(optional) is the name of a custom write function that is called whenever the value of the field is written out to a file as part of serialization.

  • description is a string that provides a brief description of the field, which will be displayed in the editors.

Example

Let's say we want to add a protected field to an object class in Torque3D that represents the object's name. The following code shows how to do this using the addProtectedField function:

void MyObjectClass::initPersistFields()
{
   Parent::initPersistFields();

   addProtectedField( "name", TypeString, offset(MyObjectClass, mHeight), &setName, &getName, "The name of the object" );
}

bool MyObjectClass::setName(void *obj, const char *array, const char *data)
{
   MyObjectClass* myObj = static_cast<MyObjectClass*>(obj);
   if (myObj )
      myObj->setName(data); //Call to our normal class set function
   return false;
}

const char* MyObjectClass::getName(void* obj, const char* data)
{
   MyObjectClass* myObj = static_cast<MyObjectClass*>(obj);
   
   //This lets us check if we have a valid name, and if not, return 
   //a sane value
   if(myObj->getName())
      return myObj->getName(); //The value is good, so use the normal class get function
   
   return StringTable::EmptyString;
}

In this example, we are adding a new protected field to the MyObjectClass object class, with the data type TypeString, defining the offset for the MyObjectClass and mHeight variable, custom set and get functions setName and getName, and a description of "The name of the object".

For simplicity, and because it is not commonly used, we ignored the writeFunction in this example.

It's important to note that, similar to how initPersistFields() itself is a static function because it is invoked for the class configuration, not a specific object itself, the set, get, and write functions called back are also defined as static in the class header.

This is why you see that there is a static_cast applied to go from the void* to the actual object being modified.

With this implementation, the protected field can be accessed and modified both in the engine's editor and in scripts, and the custom set and get functions ensure that the value of the field is properly set and retrieved.

PreviousExposing Object Classes to ScriptNextAdding a New Library to the Engine

Last updated 2 years ago