stingray.VectorField object reference

Description

Represents a vector field.

A vector field is a function that returns a Vector3 (actually a Vector4, but usually we are only interested in the first three components) for each point in space. It is typically used to represent things like wind, but it can also be used for other concepts based on field effects, like magnetism.

A game world can hold an arbitrary number of vector fields identified by name. For example, the vector field for wind is typically called "wind".

To access a vector field, use stingray.World.vector_field(). Vector fields can be made to affect physics objects by using the stingray.PhysicsWorld.apply_wind() function. Similarly, vector fields can be made to affect particles by using the Wind: From Vector Field particle controller.

Effects are added to a vector field by calling stingray.VectorField.add(). Effects are defined in resource files with the .vector_field extension. These resources define a vector field effect using a HLSL-like language. For example:

const float4 center = float4(0,0,0,0);
const float4 up = float4(0,0,1,0);
const float4 speed = float4(1,1,1,1);
const float4 radius = float4(5,5,5,5);

struct vf_in
{
float4 position : CHANNEL0;
float4 wind : CHANNEL1;
};

struct vf_out
{
float4 wind : CHANNEL1;
};

void whirl(in vf_in in, out vf_out out)
{
float4 r = in.position - center;
out.wind = in.wind + speed * cross(up, r) / dot(r,r) * radius;
}

You can also use the vector_fields console command in-game to draw vector fields for debugging purposes.

Constructors and accessors

stingray.World.vector_field()

Other related reference items

	stingray.PhysicsWorld.apply_wind()
	Physics

Related help topics

Creating Gameplay > Physics > Set up vector field (wind) effects

Functions

add ( self, effect, parameters, settings ) : integer Adds a new effect to the vector field.

Parameters

self :	stingray.VectorField	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
effect :	string	The name of the .vector_field resource that defines the effect.
parameters :	table	A table that specifies values for global constants defined in the effect's data file. The keys in this table should correspond to the names of global parameters in the effect. Each value in this table may be a number, a Vector3, or a Quaternion. For example, to control the whirl effect example shown in the VectorField object description, you can specify a parameter table as follows: {center = Vector3(4,4,0), radius = 5, speed = 10}
settings :	table	A table that provides settings for the effect.

Returns

integer

An ID that can be used to identify this effect when calling stingray.VectorField.change() and stingray.VectorField.remove().

Other related reference items

	physics_vector_field_settings
	stingray.VectorField.change()

change ( self, id, effect, parameters, settings ) Changes the effect with the specified ID to use the specified parameters.

Parameters

self :	stingray.VectorField	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
id :	integer	The ID of a vector field effect previously set up by a call to add().
effect :	string	The name of the .vector_field resource that defines the effect.
parameters :	table	A table that specifies values for global constants defined in the effect's data file. The keys in this table should correspond to the names of global parameters in the effect. Each value in this table may be a number, a Vector3, or a Quaternion. For example, to control the whirl effect example shown in the VectorField object description, you can specify a parameter table as follows: {center = Vector3(4,4,0), radius = 5, speed = 10}
settings :	table	A table that provides settings for the effect

Returns

This function does not return any values.

If the effect with the id does not exist or has played out, this function has no effect.

Other related reference items

	physics_vector_field_settings
	stingray.VectorField.add()

evaluate ( self, point ) : stingray.Vector3 Applies the vector field to the specified input position, and returns the transformed position.

Parameters

self :	stingray.VectorField	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
point :	stingray.Vector3	An input position.

Returns

stingray.Vector3

The output position, after the vector field has been applied to the input position.

evaluate ( self, points ) : stingray.Vector3[] Applies the vector field to the specified input positions, and returns a list of the transformed positions.

Parameters

self :	stingray.VectorField	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
points :	stingray.Vector3[]	A table of input positions. The [] notation indicates that this type is an array: a table in which the keys of the members are sequential integers, and the value of each element is an instance of the type shown.

Returns

stingray.Vector3[]

A table of output positions, after the vector field has been applied to each of the input positions. The [] notation indicates that this type is an array: a table in which the keys of the members are sequential integers, and the value of each element is an instance of the type shown.

remove ( self, id ) Removes the effect with the specified ID.

Parameters

self :	stingray.VectorField	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
id :	integer	The ID of the vector field effect you want to remove.

Returns

This function does not return any values.

If the effect does not exist, this function has no effect.

Other related reference items

stingray.VectorField.add()