Toolkit Fundamentals

Table of Contents

• Architecture fundamentals
• Development environment
• Toolkit organization
• Development patterns

This section covers the foundational concepts that inform all subsequent development work: the dual-process architecture, plugin loading mechanism, build system configuration, and development environment setup.

Architecture fundamentals

Process architecture

VR-Engage operates as a distributed system with two cooperating processes, even when running on a single machine. This architectural decision enables high frame rates for visualization while maintaining simulation fidelity, and provides clean separation between user-facing code and simulation logic.

The frontend process (vrEngage.exe) builds upon VR-Vantage and handles everything the user directly experiences. This includes 3D rendering, head-mounted display integration, input device polling, audio playback, and user interface presentation. The frontend maintains a local copy of entity state for smooth rendering but defers to the backend for authoritative simulation decisions.

The backend process (vrEngageSim.exe) builds upon VR-Forces and manages the authoritative simulation state. This includes physics calculations, damage assessment, sensor modeling, AI behavior, and network protocol handling. The backend publishes state updates that the frontend consumes for visualization, and receives input commands that the frontend forwards from user actions.

When developing new features, consider which process should own each responsibility. User-facing concerns like custom HUDs, input mappings, or visual effects belong in the frontend. Simulation concerns like physics models or weapon ballistics, belong in the backend. State that both processes need access to flows through the messaging layer described in Inter-Process Communication.

Plugin system

VR-Engage uses a plugin-based architecture that loads custom code at runtime. Plugins are compiled as Dynamic Link Libraries (DLLs) that register factories, components, and services with the application framework. This approach enables extending VR-Engage without modifying or rebuilding the core application.

Frontend plugins extend the player station with custom UI components, input handlers, and control logic. They export an initPlayerStationModule() entry point and are placed in plugins64/vrEngage/release/. VR-Engage automatically discovers and loads all plugins in this directory at startup.

Simulation plugins (also called backend plugins) extend the VR-Forces simulation engine with custom entity behaviors, physics models, and network handlers. They use VR-Forces entry points (DtInitializeVrfPlugin()) and require explicit configuration via XML files in appData/plugins/.

Shared libraries contain code used by both frontend and simulation plugins, such as message definitions or utility functions. They are deployed to bin64/ where both processes can load them.

For detailed plugin implementation patterns, entry point signatures, and complete code examples, see Plugin Architecture.

Development environment

Plugin development requires Visual Studio 2022, CMake 3.16+, Qt 5.15.x, and the VR-Engage Toolkit. These tools work together to compile plugins against the VR-Engage SDK and deploy them to the correct runtime directories.

The build process uses CMake to generate Visual Studio solutions. VR-Engage provides CMake configuration files in the toolkit's cmake/ directory that define imported targets for linking against VR-Engage libraries. Plugins use find_package(VREngage) to locate these targets, then link against libraries like VREngage::vrePlayerStation for frontend plugins or VR-Forces libraries for simulation plugins.

Environment variables tell the build system where to find dependencies. The examples build system computes MAK_VREDIR automatically from the directory structure, but requires MAK_VRFDIR for VR-Forces, MAK_VRLDIR for VR-Link, and QTDIR for Qt.

For step-by-step setup instructions, environment variable configuration, and build commands, see Environment Setup & Build Guide. The examples directory includes a setupEnv.bat script and working CMakeLists.txt files that serve as templates for new plugins.

Toolkit organization

The VR-Engage Toolkit installation organizes headers, libraries, and runtime files in this structure:

Directory	Contents
bin64/	Executables (vrEngage.exe, vrEngageSim.exe) and shared libraries
include/	Public headers organized by subsystem (framework/, vrePlayerStation/, vreMessages/)
lib64/	Import libraries for linking
plugins64/	Plugin directories: vrEngage/ (frontend), vrForces/ (simulation), vrVantage/ (graphics)
data/	Runtime data: roles, input mappings, simulation model sets
examples/	Toolkit examples with full source code
cmake/	CMake configuration files for find_package()

Headers in include/ are organized by functional area. The framework/ directory contains core abstractions. The vrePlayerStation/ directory contains frontend-specific classes. The vrfExtensions/ directory contains backend integration classes.

For details on plugin installation paths and deployment, see Plugin Architecture.

Development patterns

Several patterns appear repeatedly throughout VR-Engage toolkit development.

Common patterns

Factory registration

Components are instantiated through factories rather than direct construction. This enables configuration-driven instantiation where role files specify component types by name.

// filepath: src/myPlugin.cxx
 
// Register factory during plugin initialization
app->componentFactory().addCreator<DtMyComponent>("MyComponent");
 
// Later, framework instantiates via factory
// when role configuration references "MyComponent"

Configuration-driven initialization

Components read configuration from DtInitTable during initialization rather than hardcoding values. This enables runtime configuration through role files.

// filepath: src/myComponent.cxx
bool DtMyComponent::initialize(DtPlayerStation* player, DtInitTable& config)
{
   if (!DtPlayerComponent::initialize(player, config))
   {
      return false;
   }
 
   // Read configuration with defaults
   myMaxSpeed = config.findDataOr<double>("maxSpeed", 100.0);
   myEnableFeature = config.findDataOr<bool>("enableFeature", true);
 
   return true;
}

Message-based communication

Components communicate through published messages rather than direct method calls. This decouples components and enables cross-process communication.

// filepath: src/myComponent.h
 
class DtMyComponent : public DtPlayerComponent
{
public:
   // Handler method declaration
   DtVreMessageResult handleStatusUpdate(DtVreMessage* msg);
   // ...
};

// filepath: src/myComponent.cxx
 
// Send message on next tick
auto msg = DtMyStatusMessage::create();
msg->setStatus(currentStatus);
makVre::DtVreMessageManager::instance().queueMessage(msg);
 
// Register handler (typically in initialize)
makVre::DtVreMessageManager::instance().addHandler(
   DtMyStatusMessage::theType(),
   DtVreMessageDelegate(this, &DtMyComponent::handleStatusUpdate));
 
// Handler implementation
DtVreMessageResult DtMyComponent::handleStatusUpdate(DtVreMessage* msg)
{
   auto statusMsg = static_cast<DtMyStatusMessage*>(msg);
   // Process status update...
   return DtVreMessageResult::HANDLED;
}

Error handling

Proper error handling ensures components behave predictably during both normal operation and failure conditions.

Configuration validation

Validate configuration during initialization. Check required parameters, validate ranges, and verify dependencies before returning from initialize(). Configuration errors should prevent component activation rather than causing runtime failures.

bool DtMyComponent::initialize(DtPlayerStation* player, DtInitTable& config)
{
   if (!DtPlayerComponent::initialize(player, config))
   {
      return false;
   }
 
   // Validate required parameters
   if (!config.hasField(MyComponentConfig::requiredParameter))
   {
      LOG_WARN("MyComponent") << "Missing required parameter: "
                              << MyComponentConfig::requiredParameter << std::endl;
      return false;
   }
 
   // Validate parameter ranges
   double maxSpeed = config.findData<double>(MyComponentConfig::maxSpeed);
   if (maxSpeed <= 0.0 || maxSpeed > 500.0)
   {
      LOG_WARN("MyComponent") << "Invalid maxSpeed value: " << maxSpeed
                              << " (must be between 0 and 500)" << std::endl;
      return false;
   }
 
   return true;
}

Runtime error handling

Handle runtime errors gracefully. Backend simulation logic should continue processing despite individual component failures. Frontend components should maintain functionality when backend connections drop. Log sufficient diagnostic information to understand failure causes without exposing internal implementation details.

void DtMyComponent::tick(double deltaTime)
{
   try
   {
      updateInternalState(deltaTime);
   }
   catch (const std::exception& ex)
   {
      LOG_WARN("MyComponent") << "Error updating state: " << ex.what() << std::endl;
      // Component continues to function with stale state rather than crashing
   }
}

Logging best practices

Log sufficient diagnostic information to aid troubleshooting:

• Use appropriate log levels (INFO, WARN, FATAL, VERBOSE, DEBUG)
• Include component name and context in log messages
• Log parameter validation failures with expected ranges
• Avoid logging sensitive or excessive detail in production builds
• Use LOG_VERBOSE for debug-only output

Testing and validation

Consistent testing and validation help catch integration issues early and keep custom plugins maintainable over time.

• Start with a minimal scenario that exercises only your new components or roles.
• Verify that plugins load successfully by checking startup logs for entry-point registration and factory creation.
• Use controlled test inputs (scripted input mappings or simple roles) before introducing complex hardware setups.
• Validate backend behavior with repeatable scenarios: run the same maneuver multiple times and compare logged outputs.
• When updating toolkit or physics versions, re-run a small regression set of representative scenarios.

See also

• Player Station Framework - Component lifecycle and initialization
• Debugging Fundamentals - Diagnostic techniques

Next steps

This section covered the dual-process architecture, plugin system, and development environment. The following sections address specific implementation topics:

• Player Station Framework for user interface and input handling
• VR-Forces Integration for simulation logic and physics
• Inter-Process Communication for messaging between processes
• Role Configuration for deployment and parameter management