Merging revisions 14946-15020 of https://svn.blender.org/svnroot/bf-blender/trunk/blender

1 files changed, 30 insertions, 1 deletions

diff --git a/source/gameengine/PyDoc/KX_GameObject.py b/source/gameengine/PyDoc/KX_GameObject.py
index 8ef82b4943b..fbd896a55d1 100644
--- a/source/gameengine/PyDoc/KX_GameObject.py
+++ b/source/gameengine/PyDoc/KX_GameObject.py
@@ -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 rayCast() 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 rayCast(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 hit.
+		Ex:
+			# shoot along the axis gun-gunAim (gunAim should be collision-free)
+			ob,point,normal = gun.rayCast(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