TorqueScript/Datablocks/WheeledVehicleData

From TDN

WheeledVehicleData



WheeledVehicleData also derives from VehicleData and aids the creation of vehicles with wheels and tires. WheeledVehicleData defines fewer new fields than it's flying and hovering counterparts; these few new fields are listed in the table below.

Much additional data for wheeled vehicles is defined in the WheeledVehicleTire and WheeledVehicleSpring datablocks, which are detailed later in this reference.

Field Name Type Default Value Description
Special Effects Data
jetSound AudioProfilePtr NULL Points to the AudioProfile used to produce sounds for the jet. If specified, must point to an object of type AudioProfile. Must adhere to the semantics associated with AudioProfile*, as defined in the Torque Game Engine.
engineSound AudioProfilePtr NULL Points to the AudioProfile used to produce sounds for the engine. If specified, must point to an object of type AudioProfile. Must adhere to the semantics associated with AudioProfile*, as defined in the Torque Game Engine.
squealSound AudioProfilePtr NULL Points to the AudioProfile used to produce tire squeeling sound. If specified, must point to an object of type AudioProfile. Must adhere to the semantics associated with AudioProfile*, as defined in the Torque Game Engine.
WheelImpactSound AudioProfilePtr NULL Note: this field currently has no tangible effect in the engine's simulation.
tireEmitter ParticleEmitterDataPtr 0 Points to the ParticleEmitterDatablock used for each wheel's ParticleEmitter object (each wheel has it's own ParticleEmitter).



Physics Data
maxWheelSpeed Float 40.0 Determines the maximum speed at which the vehicle may travel. Also affects the lifetime of particles emitted by the wheel.
engineTorque Float 1.0 Scalar applied to the vehicle's throttle value in the determination of total engine torque and wheel angular velocity.
engineBrake Float 1.0 Used to determine the dampening velocity affecting a wheel's angular velocity when the vehicle is engine-braking (not actively braking, but no thrust is being applied).
brakeTorque Float 1.0 Used to determine the dampening velocity affecting a wheel's angular velocity when the vehicle is actively braking.

WheeledVehicleTire and WheeledVehicleSpring

We continue our study of datablocks which derive directly from SimDataBlock by examining the final vehicle-related datablocks in the Torque Game Engine, WheeledVehicleTire and WheeledVehicleSpring. Even though these datablocks are used in Torque's vehicle system, the datablocks themselves are simple enough that they do not need to be derived from ShapeBaseData, or even GameBaseData.

We first study the WheeledVehicleTire datablock. As its name implies, this datablock is intended to encapsulate data corresponding to vehicle tires. In the physics of wheeled vehicles, tires play an important role and Torque seeks to model their role in vehicle behavior as well as is possible in real-time. The table below offers a detailed description of each field in the WheeledVehicleTire datablock definition.

Field Name Type Default Value Description
shapeFile Filename   The path and file name of a shape file to be used for the wheel. Must adhere to the semantics associated with the Filename datatype, as defined in the engine.
radius Float 0.6 The tire's radius. The radius is determined from the boundix box of the shape provided in the shapefile field, and does not need to be specified in script. The tire should be built with it's hub axis along the object's Y-axis.
mass Float   The mass of the entire wheel. Used in the physics simulation, see the documentation for the WheeledVehicleData datablock for more information. The wheel's mass does not need to be specified in script.
staticFriction Float 1.0 Used in the physical simulation to represent the tire's surface friction when it is not slipping (has traction).
kineticFriction Float 0.5 Used in the physical simulation to represent the tire's surface friction when it is slipping (has no traction).
lateralForce Float 10.0 Used in the physical simulation to represent the tire's lateral force. Lateral force can in simple terms be considered left/right steering force. WheeledVehicles are acted upon by forces generated by their tires and the lateralForce measures the magnitude of the force exerted on the vehicle when the tires are deformed along the x-axis. With real wheeled vehicles, tires are constantly being deformed and it is the interplay of deformation forces which determines how a vehicle moves. In Torque's simulation of vehicle physics, tire deformation obviously can't be handled with absolute realism, but the interplay of a vehicle's velocity, its engine's torque and braking forces, and its wheels' friction, lateral deformation, lateralDamping, lateralRelaxation, longitudinal deformation, longitudinalDamping, and longitudinalRelaxation forces, along with its wheels' angular velocity are combined to create a robust real-time physical simulation. For this field, the larger the value supplied for the lateralForce, the larger the effect steering moves can have. In Torque tire forces are applied at a vehicle's wheel hubs.
lateralDamping Float 1.0 Measures the dampening force applied against lateral forces generated by the tire. See the lateralForce field documentation for more information on vehicle physics as they relate to wheel forces.
lateralRelaxation Float 1.0 Measures the relaxing force applied against lateral forces generated by the tire. The lateralRelaxation force measures how strongly the tire effectively un-deforms. See the lateralForce field documentation for more information on vehicle physics as they relate to wheel forces.
longitudinalForce Float 10.0 Used in the physical simulation to represent the tire's longitudinal force. Longitudinal force can in simple terms be considered forward/backward movement force. WheeledVehicles are acted upon by forces generated by their tires and the longitudinalForce measures the magnitude of the force exerted on the vehicle when the tires are deformed along the y-axis. See the lateralForce field documentation for more information on wheeled vehicle physics. For this field, the larger the value supplied for the longitudinalForce, the larger the effect acceleration/deceleration moves can have.
longitudinalDamping Float 1.0 Measures the dampening force applied against longitudinal forces generated by the tire. See the longitudinalForce field documentation for more information on longitudinal tire forces, and the laterForce field documentation for more information on general vehicle physics as they relate to wheel forces.
lateralRelaxation Float 1.0 Measures the relaxing force applied against longitudinal forces generated by the tire. The longitudinalRelaxation force measures how strongly the tire effectively un-deforms. See the longitudinalForce field documentation for more information on longitudinal tire forces, and the laterForce field documentation for more information on general vehicle physics as they relate to wheel forces.
restitution Float 1.0 Note: this field currently has no tangible effect in the engine's simulation.

Since we now have a reference for the WheeledVehicleTire datablock, the final vehicle-related datablock to study is the WheeledVehicleSpring. WheeledVehicleSprings simulate the effect of a vehicle's suspension system.

Field Name Type Default Value Description
forceFloat10.0The force of the spring. Spring forces act straight up and are applied at the spring's root position, which is defined in the vehicle's shape.
lengthFloat1.0The length of suspension travel from the root position.
DampingFloat1.0Dampening force which counter-acts the spring's force.
antiSwayForceFloat1.0Force which acts to dampen lateral sway introduced when wheels opposite eachother are extended at different lengths.

The physics of wheeled vehicles, their tires, and suspension systems can be difficult to understand. You shouldn't feel daunted if the nuanced manner in which all the fields we just examined interact with eachother doesn't immediately make perfect sense. The field descriptions offered in the above tables, and in the WheeledVehicleData datablock documentation, describe at a relatively high-level how wheeled vehicle physics are simulated in Torque and what the wheeled vehicle-related datablock fields are used for. But you should not expect to be a master of Torque's complex wheeled vehicle physics system after simply reading this datablock reference material.

Full Example Script

Taken from the Buggy from Torque\SDK\example\starter.racing\server\scripts\car.cs

This does contain audio and particle information to support the whole car. 

//-----------------------------------------------------------------------------
// Torque Game Engine 
// Copyright (C) GarageGames.com, Inc.
//-----------------------------------------------------------------------------

//-----------------------------------------------------------------------------

// Information extacted from the shape.
//
// Wheel Sequences
//    spring#        Wheel spring motion: time 0 = wheel fully extended,
//                   the hub must be displaced, but not directly animated
//                   as it will be rotated in code.
// Other Sequences
//    steering       Wheel steering: time 0 = full right, 0.5 = center
//    breakLight     Break light, time 0 = off, 1 = breaking
//
// Wheel Nodes
//    hub#           Wheel hub, the hub must be in it's upper position
//                   from which the springs are mounted.
//
// The steering and animation sequences are optional.
// The center of the shape acts as the center of mass for the car.
//-----------------------------------------------------------------------------

//---------------------------------------------------------------------------------------
// Car Vehicle Shape File
//---------------------------------------------------------------------------------------
// Vehicle Name: Car
// Version: 1.0
//---------------------------------------------------------------------------------------
datablock AudioProfile(buggyEngineSound)
{
   filename    = "~/data/sound/vehicles/buggy/engine_idle.wav";
   description = AudioClosestLooping3d;
   preload = true;
};


datablock ParticleEmitterData(TireEmitter)
{
   ejectionPeriodMS = 10;
   periodVarianceMS = 0;
   ejectionVelocity = 1;
   velocityVariance = 1.0;
   ejectionOffset   = 0.0;
   thetaMin         = 5;
   thetaMax         = 20;
   phiReferenceVel  = 0;
   phiVariance      = 360;
   overrideAdvance = false;
   particles = "TireParticle";
};

datablock ParticleData(TireParticle)
{
   textureName          = "~/data/shapes/buggy/dustParticle";
   dragCoefficient      = 2.0;
   gravityCoefficient   = -0.1;
   inheritedVelFactor   = 0.1;
   constantAcceleration = 0.0;
   lifetimeMS           = 1000;
   lifetimeVarianceMS   = 0;
   colors[0]     = "0.46 0.36 0.26 1.0";
   colors[1]     = "0.46 0.46 0.36 0.0";
   sizes[0]      = 0.50;
   sizes[1]      = 1.0;
};


//----------------------------------------------------------------------------

datablock WheeledVehicleTire(DefaultCarTire)
{
   // Tires act as springs and generate lateral and longitudinal
   // forces to move the vehicle. These distortion/spring forces
   // are what convert wheel angular velocity into forces that
   // act on the rigid body.
   shapeFile = "~/data/shapes/buggy/wheel.dts";
   staticFriction = 4;
   kineticFriction = 1.25;

   // Spring that generates lateral tire forces
   lateralForce = 18000;
   lateralDamping = 4000;
   lateralRelaxation = 1;

   // Spring that generates longitudinal tire forces
   longitudinalForce = 18000;
   longitudinalDamping = 4000;
   longitudinalRelaxation = 1;
};

datablock WheeledVehicleSpring(DefaultCarSpring)
{
   // Wheel suspension properties
   length = 0.85;             // Suspension travel
   force = 3000;              // Spring force
   damping = 600;             // Spring damping
   antiSwayForce = 3;         // Lateral anti-sway force
};

datablock WheeledVehicleData(DefaultCar)
{
   category = "Vehicles";
   shapeFile = "~/data/shapes/buggy/buggy.dts";
   emap = true;

   maxDamage = 1.0;
   destroyedLevel = 0.5;

   maxSteeringAngle = 0.785;  // Maximum steering angle, should match animation
   tireEmitter = TireEmitter; // All the tires use the same dust emitter

   // 3rd person camera settings
   cameraRoll = true;         // Roll the camera with the vehicle
   cameraMaxDist = 6;         // Far distance from vehicle
   cameraOffset = 1.5;        // Vertical offset from camera mount point
   cameraLag = 0.1;           // Velocity lag of camera
   cameraDecay = 0.75;        // Decay per sec. rate of velocity lag

   // Rigid Body
   mass = 200;
   massCenter = "0 -0.5 0";    // Center of mass for rigid body
   massBox = "0 0 0";         // Size of box used for moment of inertia,
                              // if zero it defaults to object bounding box
   drag = 0.6;                // Drag coefficient
   bodyFriction = 0.6;
   bodyRestitution = 0.4;
   minImpactSpeed = 5;        // Impacts over this invoke the script callback
   softImpactSpeed = 5;       // Play SoftImpact Sound
   hardImpactSpeed = 15;      // Play HardImpact Sound
   integration = 4;           // Physics integration: TickSec/Rate
   collisionTol = 0.1;        // Collision distance tolerance
   contactTol = 0.1;          // Contact velocity tolerance

   // Engine
   engineTorque = 4000;       // Engine power
   engineBrake = 600;         // Braking when throttle is 0
   brakeTorque = 8000;        // When brakes are applied
   maxWheelSpeed = 30;        // Engine scale by current speed / max speed

   // Energy
   maxEnergy = 100;
   jetForce = 3000;
   minJetEnergy = 30;
   jetEnergyDrain = 2;

   // Sounds
//   jetSound = ScoutThrustSound;
//   engineSound = BuggyEngineSound;
//   squealSound = ScoutSquealSound;
//   softImpactSound = SoftImpactSound;
//   hardImpactSound = HardImpactSound;
//   wheelImpactSound = WheelImpactSound;

//   explosion = VehicleExplosion;
};


//-----------------------------------------------------------------------------

function WheeledVehicleData::create(%block)
{
   %obj = new WheeledVehicle() {
      dataBlock = %block;
   };
   return(%obj);
}

//-----------------------------------------------------------------------------

function WheeledVehicleData::onAdd(%this,%obj)
{
   // Setup the car with some defaults tires & springs
   for (%i = %obj.getWheelCount() - 1; %i >= 0; %i--) {
      %obj.setWheelTire(%i,DefaultCarTire);
      %obj.setWheelSpring(%i,DefaultCarSpring);
      %obj.setWheelPowered(%i,false);
   }
   
   // Steer front tires
   %obj.setWheelSteering(0,1);
   %obj.setWheelSteering(1,1);

   // Only power the two rear wheels...
   %obj.setWheelPowered(2,true);
   %obj.setWheelPowered(3,true);
}

function WheeledVehicleData::onCollision(%this,%obj,%col,%vec,%speed)
{
   // Collision with other objects, including items
}
© GarageGames.com Home Back to Top