Move it, Shake it, Mix it up with AE 5

Move it, Shake it, Mix it up with AE 5
Alongside the release of stunning LiveCode 5.0 animationEngine 5 hits the Marketplace - and it is free with every new purchase of LiveCode 5 in October!

I really have to think hard before I can recall when I was this excited about a software release. LiveCode is my bread and butter, I've been using it for 10 years now and I am not easily impressed anymore. I really am not. However, when the first developer previews appeared on the LiveCode dev lists (it really pays being subscribed to the developer program!) I could almost smell it. This one is going to be big. I did not lose much time. Immediately I fired up animationEngine to see if it would still work with the new LiveCode engine. Some minor adjustments to the code later and I was up and running. Good I thought. This will continue to work, fine.

The wow factor
Then I spend some time reading the release notes and just went wow. While using animationEngine with the 5 engine improved redrawing speeds on my test stacks (I admit after playing with the new compositor type, layermodes and tilesizes for a while), I saw that this is the dawn of really being able to write games for mobile devices in LiveCode. Now, egomaniac as I am, I love to be part of this, so looking at the feature set in LiveCode 5 I quickly realized I could tweak animationEngine a bit to make it perform better than before. So I rewrote some ancient parts in it. Reviewing old code is always fun:

## dear future me, please forgive me 
## I am not quite sure I will understand the math behind this
# in a couple of months

was one of my favourite comments I stumbled upon when reading the sources. Well, turns out I did. :-)

So after quite a bit of cleaning up was done, I looked in more depth at the new features and discovered the changes to the intersect command. Cool I thought, very very cool. Now how can animationEngine benefit from that? What I came up with is the generic collision listener.

The Collision Listener
I have implemented a means to make controls listen to collisions with numerous other objects in your stack. You can start or stop listening for collisions at any time. animationEngine will send callback messages to the colliding controls. This will also work for objects you are dragging around with the animationEngine constraining handlers. No need to write lengthy scripts to check for collisions. Just set up your objects and let animationEngine handle the rest. And here is how it works:

Accurate collision detection used to be a CPU consuming task in LiveCode. With the introduction of the improved intersect command in LC 5.0 this changed a lot. You can now easily check for collisions of objects that use an alpha channel (images, graphics and even buttons with their icon set) AnimationEngine now uses the improved intersect tests and adds a way to listen for collisions with just a few lines of script. To be frank, this is the feature I am most fond of in animationEngine5!

Create a stack.
Create a text field and set its name to "output"
Create 6 graphic objects (we are using graphics only for the simplicity, you could also use a couple of png images, or buttons with their icon set. If you are using buttons, you need to set the following properties: opaque false ; showBorder false ; showName false ; shadow false ; hiliteBorder false ; armBorder false ; showFocusBorder false ; hiliteIcon 0 ; hoverIcon 0 )
Name your graphic objects. Set the names of them to gr1,gr2,gr3,gr4,gr5,gr6 Make sure you set the opaque of the graphics to true.

on mouseUp 
   if "animationEngine" is not among the lines of the \
          stacksInUse then
      answer \
             "This stack needs animationEngine 5 or higher to run."
      exit mouseUp
   end if
   aeStopListeningForCollisions -- this will clear the list of \
          all objects listening for collisions
   local tList 
   set the flag of me to not the flag of me
   if the flag of me then
      -- set up graphics to be draggable 
      repeat with i=1 to the number of graphics
         set the constrainRectangular of graphic i to the rect \
                of this cd -- graphics need to be opaque to be draggable
         set the opaque of graphic i to true
      end repeat 
      repeat with i = 2 to the number of graphics
         put the long id of graphic i & cr after tList 
      end repeat 
      -- remove trailing carriage return 
      delete char -1 of tList
      set the aeListenForCollisionsWith of graphic 1 to tList 
      -- right now we assume all but graphic 1 are predators
      -- you could set up lists for each graphic though
      -- aeStartListeningForCollisions
      set the label of me to "Stop listening for collisions" 
   else
      aeStopListeningForCollisions
      set the label of me to "Start listening for collisions" 
   end if
end mouseUp

The script sets up a list of graphic references (the long ID is a reference to the graphic, that identifies it uniquely). right after that a property in animationengine is set that tells the graphic with the lowest layer (the first graphic you created on the card) to listen for collisions with the other objects. As you can see there is quite a bit of overhead in the script that just checks if anmationEngine is present and to give a means to start and stop listening for collisions. The actual listening part is pretty straightforward.
Next open a script editor to edit the card script:

on aeCollision pObjects 
   put the short name of the target && "collides with" & cr & \
          pObjects into fld "output"
end aeCollision

on constrainRectangularCallBack local tObjects 
   put aeCollidingObjects() into tObjects 
   if the keys of tObjects is empty then 
      put empty into fld "outPut" 
   end if
end constrainRectangularCallBack

The first handler of the script is a callback message that is sent to the control listening for collisions. You could also put it directly into that control. AnimationEngine sends a message to the listening control (referred here as the target). The message is sent with one parameter. A list of all objects that are currently colliding with your listening control - of course only the controls that you told the target to listen to previously. The second handler you see is a callback message animationEngine sents to controls being dragged, if you are using animationEngines constrain handlers. In this demonstration constrainRectangularCallback is used to clear the output field, if no collisions occur. This is done using a function call to animationEngine. aeCollidingObject returns an array, that holds the colliding partners of all listening objects. So if you do not want to rely on messages being pushed to your controls you could instead use that function to set up a list of all colliding objects in a central place. If you like you can rely on the callback message being pushed to the listening control and use that to create your collision response or instead poll the function. This might be a matter of taste, however, the overhead of calling the function is a little bigger than reacting to the callback message. How often the tests for collisions are executed depends on the frameRate you set for animationEngine. By default this will be 25 fps. If you want to change that framerate, please look up aeSetFrameRate in the handlers section of the new animationEngine documentation PDF.

Easy to Register too!
We have also lessened stress with registering animationEngoine. If you purchase animationEngine, it will be added to your account. All you have to do after that is relicense LiveCode (Help -> Re-license LiveCode) and you're done.

LiveCode.tv
I will be holding a little presentation in this Saturday's LiveCode.tv event.

I hope you have as much fun using LiveCode 5 and animationEngine 5 as I had writing it. See you next time,