Cursor trails

 

Compatibilities:

Rating:

Creates a trail of sprites behind the cursor. There are two types of trails and you can specify the length of the trail as well as how many sprites are used in it. Also includes handlers to toggle the function on and off as well as reset the sprites. Also allows you to specify what order the trail sprites are drawn in as well as allowing for an overall shift in the z-depth to allow you to have it go behind all other sprites, or in front of them, which out having to worry about where in the score they go.

-- Routine to create a user specified trail of the cursor -- Written by Barry Swan -- gerbil@theburrow.co.uk -- www.theburrow.co.uk -- -- Drop it onto the first sprite you wish to use in the -- trail and fill in the options that appear -- -- For more help on the available option please read the -- notes that appear in the behavior inspector when this -- behavior is selected --------------------------------------------------------- property pStyle, pSprites, pGaps, pEnabled, pSpriteOrder, pLocZ property pFirstSN, plLocs, plInitial, pListPos, pListSize on beginSprite me      -- Initialise the trail      pFirstSN = me.spriteNum   pListPos = 1      -- This behavior needs at least one sprite to work      pSprites = max(1, pSprites)      -- Calculate list size needed      pListSize = pSprites * pGaps      -- Store sprite information for resetting purposes      plInitial = []   repeat with a = 1 to pSprites     tSN = pFirstSN + a - 1     add plInitial, [#loc: sprite(tSN).loc, #locz: sprite(tSN).locz, #visible: sprite(tSN).visible]   end repeat      -- Set up sprites and list as appropriate      if pEnabled then EnableTrail me   else DisableTrail me    end on endSprite me      -- Clear up sprites afterwards      ResetSprites me    end on prepareFrame me      -- Manage the trail if enabled      if pEnabled then          -- Update the list          tlPos = the mouseLoc          -- Update the two trail methods at different times          if pStyle = #follow then              -- Update this every frame              tUpdateThisFrame = TRUE     else if pStyle = #static AND (pListPos mod pGaps = 1 OR pGaps < 2) then              -- This is the right frame to update using the static trail method              tUpdateThisFrame = TRUE     else              -- Don't update this frame using the static trail method              tUpdateThisFrame = FALSE     end if          -- Update the trail if necessary          if tUpdateThisFrame then              -- Store the current mouse position in the list              plLocs[pListPos] = tlPos              -- Go through the trail sprites in order              repeat with a =1 to pSprites                  -- Work out which sprite we are working on                  tSN = pFirstSN + a - 1                  -- Draw trail in specified order                  if pSpriteOrder then tLocZ = tSN         else tLocZ = pFirstSN + pSprites - a                  -- Add specified z depth                  tLocZ = tLocZ + pLocZ                  -- Draw the trail sprite in the correct position                  tOffset = ((pListPos - 1) + (a - 1) * pGaps) mod pListSize + 1         sprite(tSN).loc = plLocs[tOffset]         sprite(tSN).locZ = tLocZ       end repeat     end if          -- Decrease and loop the pos counter          pListPos = pListPos - 1     if pListPos = 0 then pListPos = pListSize   end if    end on EnableTrail me      -- Initialise and begin using trail      pListPos = 1   InitialiseList me   pEnabled = TRUE      -- Go through each trail sprite setting it to the start values      repeat with a = 1 to pSprites     tSN = pFirstSN + a - 1     sprite(tSN).loc = plLocs[1]     sprite(tSN).visible = TRUE   end repeat    end on DisableTrail me      -- (Temporarily) disable the trail feature and hide trail      pEnabled = FALSE   repeat with a = 1 to pSprites     tSN = pFirstSN + a - 1     sprite(tSN).visible = FALSE   end repeat    end on StopTrail me      -- Cancels the trail and resets sprites to what they were before      pEnabled = FALSE   ResetSprites me    end on InitialiseList me      -- Creates a default list to store the mouse positions      tlPos = the mouseLoc      plLocs = []   repeat with a = 1 to pListSize     add plLocs, tlPos   end repeat    end on ResetSprites me      -- Restore sprites to their position and visibilty   -- states before this behaviour was called      repeat with a = 1 to pSprites     tSN = pFirstSN + a - 1     sprite(tSN).loc = plInitial[a].loc     sprite(tSN).locz = plInitial[a].locz     sprite(tSN).visible = plInitial[a].visible   end repeat    end on getPropertyDescriptionList me      -- Initialise the property description box data      tlData = [:]   tlData[#pStyle] = [#format: #symbol, #default: #follow, #range: [#follow, #static], #comment: "How should the trail be made:"]   tlData[#pSprites] = [#format: #integer, #default: 1, #comment: "How many sprites to use for the trail:"]   tlData[#pGaps] = [#format: #integer, #default: 3, #range: [#min: 1, #max: 10], #comment: "How close together should the trail be (1 = Close, 10 = Distant):"]   tlData[#pEnabled] = [#format: #boolean, #default: TRUE, #comment: "Use the trail immediately:"]   tlData[#pSpriteOrder] = [#format: #boolean, #default: FALSE, #comment: "Trail follows channel order:"]   tlData[#pLocZ] = [#format: #integer, #default: 0, #comment: "Add this to the locZ to draw trail at different depth on the stage:"]      -- Return the property description box data      return tlData    end on getBehaviorDescription me      -- Create the text to be shown in the behavior inspector      tText = "[Sprite] Cursor trail" & RETURN & RETURN      tText = tText & "Use this behaviour to create and manage cursor trails. Sprites required for the trail must be in consecutive channel order. The first sprite will be closest to the cursor while the last used will be furthest (in order) from the cursor. Set their graphics / inks etc. accordingly. Use this behavior by dropping it in the lowest channel numbered sprite to be used for the trail, and setting the options that appear. When the sprite this behaviour is attached to ends for whatever reason, then all the sprites used in the trail are reset to their initial location, z depth, and visibility." & RETURN & RETURN      tText = tText & "-- Options in the property description list:" & RETURN & RETURN   tText = tText & "How should the trail be made: [#follow | #static ]" & RETURN   tText = tText & "#follow creates a trail that follows the cursor precisely. #static creates a trail that places itself at regular intervals at the cursor's current position." & RETURN & RETURN   tText = tText & "How many sprites to use for the trail: [1 to the maximum number of channels free]" & RETURN   tText = tText & "These sprites must be in consecutive channel order from the first sprite in the trail." & RETURN & RETURN   tText = tText & "How close together should the trail be (1 = Close, 10 = Distant): [1 to 10]" & RETURN   tText = tText & "Each unit here specifies how many frames behind the previous one the trail sprite is. Higher numbers create a much more distinct  trail." & RETURN & RETURN   tText = tText & "Use the trail immediately: [TRUE | FALSE]" & RETURN   tText = tText & "Active the trail immediately else initialise it but do not show it. See below on controlling the trail more." & RETURN & RETURN   tText = tText & "Trail follows channel order: [TRUE | FALSE]" & RETURN   tText = tText & "If this is set to TRUE then sprites use their channel order for depth. This means the trail sprites nearest the cursor will be obscured by those further away. Set this to FALSE for the first trail sprite to be on top of those further below it in the score." & RETURN & RETURN   tText = tText & "Add this to the locZ to draw trail at different depth on the stage: [-2 billion to +2 billion]" & RETURN   tText = tText & "Use this to prevent you having to place the trail sprites in any particular position in the score. Add a number greater than the channels used in the movie to make the trail always appear above them on the stage, or leave at zero for them to stick to the channels they are placed in. If you use a large enough negative number you can set it so the trail always go behind everything on the stage." & RETURN & RETURN     tText = tText & "-- Handlers that can be called to affect the trail during run-time:" & RETURN & RETURN     tText = tText & "EnableTrail()" & RETURN   tText = tText & "Call this to start the trail working. You can either do this after calling DisableTrail() or StopTrail(), or if you set this behaviour to not use the trail by default." & RETURN & RETURN     tText = tText & "DisableTrail()" & RETURN   tText = tText & "Pauses the trail and makes all the sprites used in the trail invisible. Restart again by calling EnableTrail()" & RETURN & RETURN      tText = tText & "StopTrail()" & RETURN   tText = tText & "This stops the trail from being used and resets all the sprites used in the trail to their initial position, z depth, and visible state. You can still call EnableTrail() to restart them." & RETURN & RETURN    tText = tText & "Written by Barry Swan" & RETURN   tText = tText & "gerbil@theburrow.co.uk" & RETURN   tText = tText & "www.theburrow.co.uk"   -- Return the complete help text   return tText end