Taking the example from the documentation, it appears to return the center of the sphere that collides with the object.
You can find the contact point using GetObjectRaycastX/Y/Z() and GetObjectRaycastNormalX/Y/Z() to cast a ray through the original collision object.
As far as i can see (and i can't see very far) the normals point in the OPPOSITE direction to the contact. So if you use SetObjectLookAt() to look along the normals it will look in the opposite direction.
Not sure if you have to flip them when casting a ray.
//(AGK version: 108.24)
//Submitted: 2014-12-15 17:23:49
// this example should work with AGK V1 and AGK V2
// use the ws key or the on screen joystick to move the sphere
// if the sphere cast intersects the box, the box will turn red
// the green and red sphere are cosmetic so you can see where the start and end of the sphere cast is
// set a radius for the sphere cast
radius# = 20.0
// make a box (this will automatically be position at 0,0,0)
CreateObjectBox(1,50,1,50)
SetObjectCollisionMode(1,1)
// make a green sphere that will have the same radius as the sphere cast and position it
CreateObjectSphere(2,radius#*2,12,12)
SetObjectColor(2,0,255,0,255)
SetObjectPosition(2,-50,0,50)
// make a red sphere that will have the same radius as the sphere cast
CreateObjectSphere(3,radius#*2,12,12)
SetObjectColor(3,255,0,0,255)
SetObjectPosition(3,50,0,50)
// create a directional light
//CreateLightDirectional(1,-1,-1,0,255,255,255)
// position and orientate camera
SetCameraPosition(1,0,200,0)
SetCameraLookAt(1,0,0,0,0)
cylinder = CreateObjectCylinder(100, radius# * 2, 8)
RotateObjectLocalX(cylinder, 90)
SetObjectPosition(cylinder, 0, 0, 50)
FixObjectPivot(cylinder)
SetObjectTransparency(cylinder, 1)
SetObjectAlpha(cylinder, 0x50)
hit=CreateObjectSphere(radius# * 2, 16, 16)
SetObjectTransparency(hit, 1)
SetObjectAlpha(hit, 0x70)
normal = CreateObjectCylinder(100, 1, 8)
RotateObjectLocalX(normal, 90)
SetObjectPosition(normal, 0, 0, -50)
FixObjectPivot(normal)
SetObjectTransparency(normal, 1)
SetObjectAlpha(normal, 0x50)
cast = 1
// main loop
do
if GetRawKeyPressed(asc("R"))
cast = 1
endif
// get player input
joystick_y# = GetJoyStickY()*-1
// move the sphere
MoveObjectLocalZ(2, GetRawKeyState(38) - GetRawKeyState(40) )
// use the spheres to determine the start (old) and end (new) points of the sphere cast
old_x# = GetObjectX(2)
old_y# = GetObjectY(2)
old_z# = GetObjectZ(2)
new_x# = GetObjectX(3)
new_y# = GetObjectY(3)
new_z# = GetObjectZ(3)
SetObjectPosition(cylinder, old_x#, old_y#, old_z#)
SetObjectLookAt(cylinder, new_x#, new_y#, new_z#, 0)
if cast
if ObjectSphereSlide(1,old_x#,old_y#,old_z#,new_x#,new_y#,new_z#,radius#) = 0
// if the box is not intersected by the sphere cast then color it white
SetObjectColor(1,255,255,255,255)
else
// if the box is intersected by the sphere cast then color it red
SetObjectColor(1,255,0,0,255)
SetObjectPosition(hit, GetObjectRayCastX(0), GetObjectRayCastY(0), GetObjectRayCastZ(0))
SetObjectPosition(normal, GetObjectRayCastX(0), GetObjectRayCastY(0), GetObjectRayCastZ(0))
SetObjectLookAt(normal, GetObjectRayCastX(0)+GetObjectRayCastNormalX(0), GetObjectRayCastY(0)+GetObjectRayCastNormalY(0), GetObjectRayCastZ(0)+GetObjectRayCastNormalZ(0), 0)
cast = 0
endif
endif
print("Use UP/DOWN keys to move green ball")
sync()
loop