First, see DocumentationPhysics for a general explanation of the collision system. Also see WorldFoundryTechnicalNotes (and search for text string "collision" in the page), AnalysisOfCurrentPhysicsSystem

Now, on to the code details. Just notes for now. grep these strings in the source code and read the source.

• collision interaction table source/oas/objects.mac
• CI_PHYSICS , CI_PHYSICS
• CI_SPECIAL, *
• MsgPort::COLLISION - is this unused? I can't find any code which actually processes this message except to throw it away.
• MsgPort::SPECIAL_COLLISION - sent to the object(s) in a collision pair which have collision interaction type CI_SPECIAL. This mesage can be handled in update()
• Also see room.cc line 545, where the collisionInteraction type is checked and either handled via physics (for physics-physics interactions) or dispatched to a special collision handler
• see example in explode.cc, Explode::update(), where all SPECIAL_COLLISION messages are processed
• * The rule sppears to be: if special collision handling is needed, declare it as such in objects.mac
• * The collision system automatically generates a special collision message in this case
• * Handle this message in update()
• * But what is e.g. meant by the collision interaction pair (CI_PHYSICS, CI_SPECIAL)? One is handled physically, the other specially? What happens in non-CI_SPECIAL interaction?
• ** According to collisio.cc, DispatchCollisionMessages, the pair (CI_PHYSICS, CI_SPECIAL) causes no special message to be sent to the CI_PHYSICS object. So nothing special happens to the CI_PHYSICS object - it apparently proceeds as if no collision had occurred. The CI_SPECIAL object apparently has to manipulate the CI_PHYSICS object if it wants to change it in response to the collision.
• * Here are the entries for explosions in objects.mac
• ****COLTABLEENTRY(Explode,Explode,CI_SPECIAL,CI_SPECIAL)
• ****COLTABLEENTRY(Explode,Enemy,CI_SPECIAL,CI_NOTHING)
• ****COLTABLEENTRY(Explode,Player,CI_SPECIAL,CI_NOTHING)
• ****COLTABLEENTRY(Explode,Missile,CI_SPECIAL,CI_NOTHING)
• ****COLTABLEENTRY(Explode,Spike,CI_SPECIAL,CI_NOTHING)
• ****COLTABLEENTRY(Explode,Platform,CI_SPECIAL,CI_NOTHING)
• * From this we can deduce that the special explosion handling (e.g. explode<-->player) also pushes the player around, and that the player in this case has NO direct response to the collision; only the explosion responds to the collision and responds by moving the player. Indeed, this appears exactly to be the case in Explode::update(), where it gets a pointer to the other actor (e.g. the player) and pushes it back with a force.
• ** So it seems that the valid combinations are
• * CI_PHYSICS, CI_PHYSICS - each object reacts physically. NOTE that both objects do not have to have their "Mobility" set to physics; one can for instance be path-controlled or anchored. (It makes no sense if neither object is physics-controlled, however.) See function ResolveCollisionEvent(), which makes sure that at least one actor os physically controlled, then handles the collision.
• * CI_SPECIAL, CI_SPECIAL - both objects react specially (in their update() routine, responding to a SPECIAL_COLLISION message)
• * CI_SPECIAL, CI_NOTHING and vice versa - one object does nothing, the other object reacts specially (in its update() routine, responding nto a SPECIAL_COLLISION message)
• * CI_PHYSICS and CI_SPECIAL appear not to be combined - physical behavior requires participation of both objects
• * CI_PHYSICS and CI_NOTHING appear not to be combined - physical behavior requires participation of both objects

What about scripted response in response to a collision? Add a new COLTABLEENTRY type, CI_SCRIPT. In this case a script is called on collision. But what if you want both physics and script handling? IMHO CI_SCRIPT can mean only do script processing, CI_SCRIPTANDPHYSICS can mean do script and physics. We don't need to make a fully general purpose system where all possible collision interaction types can be OR'd together, so the special case CI_SCRIPTANDPHYSICS is acceptable.

What if you want scripted and special processing (e.g. standard explosion handling plus extra scripted response)? Is CI_SCRIPTANDSPECIAL needed?

On the other hand should there be ANY "special" collision handling in the engine at all, or should CI_SPECIAL actually be handled in scripts? (Changing this requires thinking about performance issues, as well as if the update() routine - where CI_SPECIAL is currently handled - has access to additional game state not available in a script).