@John @Simeon There a bug in the documentation for spherecast. Both raycast and spherecast have lower case c’s in cast. To code spherecast, you have to use sphereCast with an upper case C. I think both should have an upper case C, rayCast and sphereCast and the documentation updated. Another thing I think is a problem is with the two rayCast and sphereCast parameters, direction and distance. Apparently the direction values need to be multiplied by the distance value. For example, if the origin is at 0,0,0 and an object is at 0,0,20, if the direction is given as 0,0,1, then the distance needs to be 20 for it to work. If the direction is set at 0,0,2, then the distance only needs to be 10. If the direction is 0,0,10, then the distance only needs to be 2. Shouldn’t the direction and distance be independent of each other. At least that’s what I’m seeing in test code.
@dave1707 That sounds like a bit of a bug. Personally I prefer using all lowercase (as in spherecast is just a compound word rather than 2 words). The direction vector should be normalized so that’s a problem too. Thanks for letting me know.
Reviewing more on the syntax of raycast and spherecast that @dave1707 mentioned and your reply, I wondering if actually both cast functions are expecting direction and distance specifically in the format I’ve read that other game engines expect (e.g. Unity):
Given target.position = vec3(x2,y2,y3) and
starting.position = vec3(x1,y1,z1)
Then ray(or sphere)cast expects the following parameters:
direction = (target.position - starting.position):normalize()
– using the vec3:normalize() function
distance = (target.position - starting.position):len()
– using the vec3:len() function
[or alternatively:
distance = (target.position:dist(starting.position))
– using the vec3:dist() function]
Is that correct? If so, as @UberGoober and others help expand Codea’s documentation, it may be helpful to include this additional information about the parameters as the proper use of the parameters may not be intuitively obvious to 3D programming novices such as myself.
Thanks 
Clarification:
The above calculations were Codea modifications of general examples in other 3D engines where one needs to figure out the trajectory to move an entity or fire a projectile from a starting.position to target.position
However, if one wanted to use ray(or sphere)cast to check in front of an object for a potential collision (in lieu of Codea not presenting having other built in functions to detect collisions in 3D) I’ve then used the following modification on the above examples:
Given nextmove.position = vec3(x2,y2,y3) position of where I’d like my entity to move and
starting.position = vec3(x1,y1,z1) position of where my entity currently resides
direction = (nextmove.position - starting.position):normalize()
distance = (nextmove.position - starting.position):len()
and feed those parameters into ray(or sphere)cast and have that cast tell me if I’d collide (hit) any rigidbody entities if I moved to that nextmove.position.
Fyi.