Newton SDK DBPro Wrapper v1.53

By Walaber
All Coding between 1.31-1.32B by Kjelle
Updated to 1.53 by Tiresius

Vehicle Commands

NDB_NewtonConstraintCreateVehicle

syntax: int = NDB_NewtonConstraintCreateVehicle( body )

	body	ID of the rigid body for chassis (integer)
	(vector 1)	temp vector used to pass values to the function

returns: index to the created vehicle joint (integer)

Comments: This command adds the Vehicle Joint to a rigid body. Any massed rigid body can be used for the vehicle chassis. Make sure you fill temp vector 1 with the world up vector (usually [0.0, 1.0, 0.0] in most projects) before calling this function!

NDB_NewtonVehicleAddTire

syntax: int = NDB_NewtonVehicleAddTire( vehicle, mass, rad, height, susShock, susSpring, susLength)

	vehicle	ID of the vehicle joint (integer)
	mass	mass of the tire (float)
	rad	radius of the tire (float)
	height	width of the tire (float)
	susShock	suspension damper for the tire (float)
	susSpring	spring constant for the tire (float)
	susLength	suspension travel for the tire (float)
	(vector 1)	temp vector used for passing values
	(matrix)	temp matrix used for passing values

returns: index to the created tire (integer)

Comments: This command adds a tire to the vehicle. First set the temp matrix (NDB_BuildMatrix) to the local matrix of the tire. Then set temp vector 1 to the pin direction vector for the axel of the tire (the direction the tire will roll around). Finally call this function, with all of the values to describe the tire.

NDB_NewtonVehicleReset

syntax: NDB_NewtonVehicleReset( vehicle )

vehicle

ID of the vehicle joint (integer)

returns: nothing.

Comments: Reset all tires velocities to zero. This function is useful for reposition the vehicle.

v1.31

NDB_NewtonVehicleRemoveTire

syntax: NDB_NewtonVehicleRemoveTire( vehicle, tire_id )

	vehicle	ID of the vehicle joint (integer)
	tire_id	ID of the tire to remove.

returns: nothing.

Comments: Removes the specified tire from the vehicle.

NDB_VehicleTireSetTorque

syntax: NDB_VehicleTireSetTorque vehicle, tire, torque

	vehicle	ID of the vehicle joint (integer)
	tire_id	ID of the tire (integer)
	torque	torque for the tire (float)

returns: nothing.

Comments: Sets the torque for the specified tire. this will cause the tire to rotate, propelling the vehicle.

NDB_VehicleTireSetSteeringAngle

syntax: NDB_VehicleTireSetSteeringAngle vehicle, tire, angle

	vehicle	ID of the vehicle joint (integer)
	tire_id	ID of the tire (integer)
	ange	steering angle for the tire (float)

returns: nothing.

Comments: Sets the steering angle for a tire. use this to steer your vehicle!

NDB_NewtonVehicleGetTireSteeringAngle

syntax: float = NDB_NewtonVehicleGetTireSteeringAngle( vehicle, tire )

	vehicle	ID of the vehicle joint (integer)
	tire_id	ID of the tire (integer)

returns: steering angle for the specified tire.

Comments: Gets the steering angle for a tire.

NDB_NewtonVehicleTireLostSideGrip

syntax: int = NDB_NewtonVehicleTireLostSideGrip( vehicle, tire )

	vehicle	ID of the vehicle joint (integer)
	tire_id	ID of the tire (integer)

returns: 1 = lost grip, 0 = has grip.

Comments: useful for determining if the car is sliding/skidding sideways.

NDB_NewtonVehicleTireLostTraction

syntax: int = NDB_NewtonVehicleTireLostTraction( vehicle, tire )

	vehicle	ID of the vehicle joint (integer)
	tire_id	ID of the tire (integer)

returns: 1 = lost traction, 0 = has traction.

Comments: useful for determining if the car`s tires are spinning.

NDB_NewtonVehicleGetTireOmega

syntax: float = NDB_NewtonVehicleGetTireOmega( vehicle, tire )

	vehicle	ID of the vehicle joint (integer)
	tire_id	ID of the tire (integer)

returns: rotating speed (omega) of the tire.

Comments: useful for determining how fast the tire is spinning.

NDB_NewtonVehicleGetTireNormalLoad

syntax: float = NDB_NewtonVehicleGetTireNormalLoad( vehicle, tire )

	vehicle	ID of the vehicle joint (integer)
	tire_id	ID of the tire (integer)

returns: load on the tire.

Comments: useful for determining how much weight is being put on the tire.

NDB_NewtonVehicleGetTireLateralSpeed

syntax: float = NDB_NewtonVehicleGetTireLateralSpeed( vehicle, tire )

	vehicle	ID of the vehicle joint (integer)
	tire_id	ID of the tire (integer)

returns: lateral speed of the tire.

Comments: this is the actual speed the tire is moving (forward/backward)

NDB_NewtonVehicleGetTireLongitudinalSpeed

syntax: float = NDB_NewtonVehicleGetTireLongitudinalSpeed( vehicle, tire )

	vehicle	ID of the vehicle joint (integer)
	tire_id	ID of the tire (integer)

returns: longitudinal speed of the tire.

Comments: this is the actual speed the tire is moving (left/right)

NDB_NewtonVehicleSetTireMaxSideSleepSpeed

syntax: NDB_NewtonVehicleSetTireMaxSideSleepSpeed vehicle, tire, speed

	vehicle	ID of the vehicle joint (integer)
	tire_id	ID of the tire (integer)
	speed	Maximum side speed before the vehicle is considered to loose side grip.

returns: Nothing.

Comments: Set the maximum side slip velocity for the tire to be considered to lose grip.

Tire operation involve a mix of elastic distortion and sliding friction. To have and idea how to code a convincing approximation of a real tire we must run some experiment and make some reflection upon the result. First we will run a static test: keeping a tire at equilibrium applying a constant load and without rolling, we will apply a lateral force perpendicular to the tire plane and applied at the tire center. If we run this experiment we will find that the tire will deflect in response to the lateral force. If we increase the magnitude of the lateral force, the magnitude of the deflection is proportional to the magnitude of the lateral force, until the tire begins to slide. This show that when a tire is not moving it behaves like a spring (elastic distortion). If we repeat this experiment but this time increasing the tire load, but still not moving the tire, we will see that the max deflection is proportional to the magnitude of the tire load. This indicates the tire behavior is proportional to two variables, the lateral force and the tire load. (Fortunately the side force in practice is a linear function of the tire load so this keeps the model simple) Now we will run the first experiment but this time we will rotate the tire with a constant angular velocity (think of those tune up machines at check up stations.) With the tire rolling at constant angular velocity if we apply a lateral force we will see that as the tire deflect, the part of the tire in contact with the floor keeps rolling and another part take its place, but this part also start to deflect, allowing the tire to move sideways with a velocity proportional to the tire rolling angular velocity. Notice that the tire does this without sliding as the part of it in contact with the floor never loses grip. Now if we increase the lateral force we will find that the lateral speed of the tire will also increase. This suggests that the side speed of the tire is proportional to the lateral force and also proportional to the rolling angular velocity. This is the tire elastic properties give then some kind of damping property when they are rolling. There is not known macroscopic mathematical model that can explain this behavior. The best we can do is to write the values of the experiment and use then to interpolate and extrapolate intermediate values. One thing we know is that the tires operates within some limits, and we can use those parameters to treat then as a constraint optimization problem, which is the Newton approach. When the tire is rolling and sideslipping is not that the tire lost grip, nor that the tire is generating some force. It is rather that the tire have the capacity to absorb some of the lateral force by sliding and convert it to side velocity, this means that for the tire to loose grip a stronger force is necessary. In another word at rest a tire will lose grip under a much lower lateral force than if the tire was rolling. In Newton this behavior is treaded as a constrain optimization problem by asking the application how much side slip velocity is the tire allow to have before it is considered to lose grip, and how much of the lateral forces generated by the rigid body dynamics will be adsorbed by the tire at a given speed. It is the application responsibility to set these parameters as close to the real tire as it chooses. This approach allows for a very wide range of behaviors form arcade, to toy cars to very realistic.

Remarks

The vehicle joint provides a rich set of interface functions to the application. Which function to use is only determined by the level of fidelity the application want to achieve. In not case the use of one method is better than other, and it may be that some tweaking and trial is necessary before the desired vehicle behavior is achieved.

Remarks

The parameters applied to a tire are reset to default values each time the update function is called. So the application should set the desired value in each simulation frame.

Remarks

This function can only be called from the vehicle update call back. It can be used by the application to generate the custom vehicle dynamics.

V1.31

NDB_NewtonVehicleSetTireSideSleepCoeficient

syntax: NDB_NewtonVehicleSetTireSideSleepCoeficient vehicle, tire, Coeficient

	vehicle	ID of the vehicle joint (integer)
	tire_id	ID of the tire (integer)
	coeficient	Side slip coeficient.

returns: nothing.

Comments: Set the coefficient that tell the engine how much of the lateral force can be absorbed by the tire.

See description of side slip on function NewtonVehicleSetTireMaxSideSleepSpeed

Remarks

The parameters applied to a tire are reset to default values each time the update function is called. So the application should set the desired value in each simulation frame.

Remarks

This function can only be called from the vehicle update call back. It can be used by the application to generate the custom vehicle dynamics.

v1.31

NDB_NewtonVehicleSetTireMaxLongitudinalSlideSpeed

syntax: NDB_NewtonVehicleSetTireMaxLongitudinalSlideSpeed vehicle, tire, speed

	vehicle	ID of the vehicle joint (integer)
	tire_id	ID of the tire (integer)
	speed	Maximum side speed before the vehicle is considered to loose side traction.

returns: nothing.

Comments: Set the maximum side slide velocity for the tire to be considered to lose traction.

Remarks

The explanation of longitudinal slide is similar to the side slip, however it is not so critical to achieve realistic behavior. See description of side slip on function NewtonVehicleSetTireMaxSideSleepSpeed

Remarks

The parameters applied to a tire are reset to default values each time the update function is called. So the application should set the desired value in each simulation frame.

Remarks

This function can only be called from the vehicle update call back. It can be used by the application to generate the custom vehicle dynamics.

v1.31

NDB_NewtonVehicleSetTireLongitudinalSlideCoeficient

syntax: NDB_NewtonVehicleGetTireLongitudinalSpeed vehicle, tire, coeficient

	vehicle	ID of the vehicle joint (integer)
	tire_id	ID of the tire (integer)
	coeficient	longitudinal slide coefficient.

returns: Nothing.

Comments: Set the coefficient that tell the engine how much of the longitudinal force can be absorbed by the tire.

Remarks

The parameters applied to a tire are reset to default values each time the update function is called. So the application should set the desired value in each simulation frame.

Remarks

This function can only be called from the vehicle update call back. It can be used by the application to generate the custom vehicle dynamics.

NDB_VehicleTireSetMaxBrake

syntax: NDB_VehicleTireSetMaxBrake vehicle, tire, maxbrake

	vehicle	ID of the vehicle joint (integer)
	tire_id	ID of the tire (integer)
	maxbrake	maximum braking force the tire can handle (float)

returns: nothing.

Comments: set this value to the absolute max braking force the tire can handle. then when you turn on the brakes for the tire, Newton sill calculate the necessary force to stop the tire. if it's less than this maximum, it'll lock the tire. if it's more, it'll apply this amount.

NDB_VehicleTireBrakesOn

syntax: NDB_VehicleTireBrakesOn vehicle, tire, flag

	vehicle	ID of the vehicle joint (integer)
	tire_id	ID of the tire (integer)
	flag	1 = brakes on, 0 = brakes off (integer)

returns: nothing.

Comments: use this function to turn the brakes on/off for a tire.

NDB_VehicleTireSetDBProData

syntax: NDB_VehicleTireSetDBProData vehicle, tire, tire_obj

	vehicle	ID of the vehicle joint (integer)
	tire_id	ID of the tire (integer)
	tire_obj	Dark basic object to use as the visual object for the tire (integer)

returns: nothing.

Comments: use this function to set which object represents the vehicle tire. it will be positioned and rotated automatically by Newton for you.

NDB_VehicleExist

syntax: int = NDB_VehicleExist( vehicle )

vehicle

ID of the vehicle joint (integer)

returns: 1 = vehicle exists, 0 = behicle does not exist..

NDB_DestroyVehicle

syntax: NDB_DestroyVehicle vehicle

vehicle

ID of the vehicle joint (integer)

returns: nothing.

Comments: use this function to destroy a vehicle joint.