SceneMan:CastMORay

From Data Realms Wiki

Function

This function is used to check for movable objects along a given vector, from start to end. If an object is detected, the ray terminates, and the function outputs the ID of the detected object. If the ray fails to hit anything with an ID, OR hits terrain, nil is returned.

Syntax

SceneMan:CastMORay(Vector1, Vector2, ID, Team, Material ID, Boolean, Integer)

Vector1: The absolute starting vector of the ray. In other words, where the ray starts. An input of Vector(300,200) starts the ray at x = 300 and y = 200.

Vector2: The relative vector to trace along. An input of Vector(10,-5) thus casts the ray from (300,200) to (310,195).

ID: The ID of an object to ignore. The ray will not detect the object with this ID or any children of this object (setting it to the ID of an actors torso will make the ray ignore all limbs and armor as well), and will pass through unhindered.

Team: An integer defining objects of which team to ignore. Setting this to 1 will have the ray pass through anything belonging to team 1, for example. Do note, however, that Team 1 AKA Red Team in game corresponds to team 0 in the code, so you have to subtract 1 from the in-game team number in order to get the right value. This can also be self.Team or self.IgnoresWhichTeam if it should inherit the team of the object calling the function. Setting a negative value below -1 or a positive value above 3 will make it hit all teams.

Material ID: The ID of a material to ignore hits with, in addition to air (which is always ignored). Grass, for example, has a material ID of 128, so setting this argument to 128 will make the ray pass through grass.

Boolean: Whether to ignore hits with any terrain or not. Setting this to "true" will make the ray pass through all terrain types, thus allowing the ray to detect objects behind walls. Opposite is true when you set it to "false", as this makes the ray stop when hitting terrain.

Integer: The number of pixels to skip ahead for every pixel checked. Setting it to 1 will make the ray check every other pixel, 4 will check every 5th pixel and so on. 0 makes it check every single pixel. This is for optimization, since it can take a lot of power if used too frequently.

Useful co-functions

Raycasting doesn't automatically react to changes in rotation or horizontal flipping, so applying the following to Vector2 can be useful:

Vector(X,Y):RadRotate(angle) - Rotates the vector to have an identical magnitude in the given absolute angle. Note that setting this to self.RotAngle makes the ray always be cast in the objects relative front.

Vector(X,Y):GetXFlipped(boolean) - Whether to flip the X component of the vector or not. Since most actors can flip horizontally, setting the boolean to self.HFlipped will make the ray automatically correct itself when the object flips.

If you're seeking to cast a ray that requires both flipping and rotation to be changable (i.e. a laser from a gun held by an AHuman), you can combine the two:

(Vector(X,Y):GetXFlipped(boolean)):RadRotate(angle)

This counts as a single argument, and is much easier than making pre-emptive corrections based on rotation and flipping.

You may also want to get a pointer to the object you've hit rather than just the ID, which is where this function comes in:

MovableMan:GetMOFromID(ID) - Gets a pointer to the object that the ID refers to, similar to "actor" and such.

Since an MORay outputs an ID when it hits something, you can just put the output of the MORay in as the singular argument. However, since an MORay outputs nil if it fails to hit an object with an ID, you may want to check that the variable is not equal to nil before proceeding. An example:

local Vector2 = (Vector(100,0):GetXFlipped(self.HFlipped)):RadRotate(self.RotAngle);

self.ray = SceneMan:CastMORay(self.Pos, Vector2, self.RootID, self.Team, 128, false, 1);

if self.ray ~= nil then

self.object = MovableMan:GetMOFromID(self.ray);

end

If we were to append this to a gun held by an actor, it would cast a ray 100 pixels in front of the guns position, which ignores both the actor holding it and his teammates, passes through grass, is halted by any other terrain, and skips every other pixel. This ray is automatically corrected in response to the actor aiming or flipping. If the ray then hits something, self.object will become a pointer to this object, allowing you to do all kinds of lovely things.