BGE patch: add rayCastToEx(), an extended version of rayCastTo() for use in game...
[blender.git] / source / gameengine / PyDoc / KX_GameObject.py
index 8ef82b4943b3d76e5c00776d51b258c7cdbe84cf..b0f55b4ad7a2a0f726d21e4a8a548d99c58d924d 100644 (file)
@@ -174,9 +174,10 @@ class KX_GameObject:
 
                The ray is always casted from the center of the object, ignoring the object itself.
                The ray is casted towards the center of another object or an explicit [x,y,z] point.
+               Use rayCastToEx() if you need to retrieve the hit point 
 
                @param other: [x,y,z] or object towards which the ray is casted
-               @type other: L{KX_GameObject} or string
+               @type other: L{KX_GameObject} or 3-tuple
                @param dist: max distance to look (can be negative => look behind); 0 or omitted => detect up to other
                @type dist: float
                @param prop: property name that object must have; can be omitted => detect any object
@@ -184,4 +185,32 @@ class KX_GameObject:
                @rtype: L{KX_GameObject}
                @return: the first object hit or None if no object or object does not match prop
                """
+       def rayCastToEx(to,from,dist,prop):
+               """
+               Look from a point/object to another point/object and find first object hit within dist that matches prop.
+               Returns a 3-tuple with object reference, hit point and hit normal or (None,None,None) if no object hit.
+               Ex:
+                       # shoot along the axis gun-gunAim (gunAim should be collision-free)
+                       ob,point,normal = gun.rayCastToEx(gunAim,None,50)
+                       if ob:
+                               # hit something
+
+               Notes:                          
+               The ray ignores the object on which the method is called.
+               If is casted from/to object center or explicit [x,y,z] points.
+               The ray does not have X-Ray capability: the first object hit (other than self object) stops the ray
+               If a property was specified and the first object hit does not have that property, there is no hit
+               The     ray ignores collision-free objects
+
+               @param to: [x,y,z] or object to which the ray is casted
+               @type to: L{KX_GameObject} or 3-tuple
+               @param from: [x,y,z] or object from which the ray is casted; None or omitted => use self object center
+               @type from: L{KX_GameObject} or 3-tuple or None
+               @param dist: max distance to look (can be negative => look behind); 0 or omitted => detect up to to
+               @type dist: float
+               @param prop: property name that object must have; can be omitted => detect any object
+               @type prop: string
+               @rtype: 3-tuple (L{KX_GameObject}, 3-tuple (x,y,z), 3-tuple (nx,ny,nz))
+               @return: (object,hitpoint,hitnormal) or (None,None,None)
+               """
        
\ No newline at end of file