--------------------------------------------------------------------
-- Add Script to Sprite (at runtime)
--------------------------------------------------------------------
-- Script Type: Movie
--------------------------------------------------------------------

--------------------------------------------------------------------
-- LICENSE: FREEWARE
-- This source code is copyright Killing Moon Ltd. 2003
--
-- You may use this code freely, but if you redistribute the source
-- code the you must abide by the following restrictions:
-- 
-- 1 - If the code is unmodified, then all the comments must remain
--     intact and in their original form.
--
-- 2 - If the code is modified then either:
--   2(a) - All the original comments must be removed. You may
--          credit the original author if you wish, but must make
--          clear that your version is not identical to the
--          original version.
--   2(b) - You must add clear documentation of ALL your alterations
--          and additions to the code in the source comments.
--          Additionall, you must place a clear notice at the top
--          of the file that the source code has been modified.
--
-- Code written by Robert Tweed.
-- Email: robert@killingmoon.com
-- Website: http://www.killingmoon.com/director/
--

--------------------------------------------------------------------
-- VERSION HISTORY:
--
-- 2004.05.01: Version 1.1 by Robert Tweed
--             addScriptToSprite now returns a value
--
-- 2003.12.01: Version 1.0 by Robert Tweed
--

---------------------------------------------------------------------------------
-- NAME: addScriptToSprite
-- CLASS: Public Handler
--
-- DESCRIPTION:
--     Instantiates a script and attaches it to a sprite.
--
-- PARAMETERS:
--
--     aSprite - Sprite channel number or a sprite object.
--
--     aScriptName - The name of a script to instantiate and attach to the sprite
--
--     aOverridePDL [optional] - List of non-default properties to be set by
--                               getPropertyDescriptionList.
--
-- RETURNS:
--     (on succss) The script instance
--     #error_not_a_sprite - The value of aSprite was not a sprite
--                           channel number or sprite instance
--
-- USAGE:
-- Different ways to add the script "My Behaviour" to sprite 10.
--
-- (1) Simple
--
--    result = addScriptToSprite( 10, "My Behaviour" )
--
-- (2) With non-default getPDL parameters.
--
--    result = addScriptToSprite( sprite(10), "My Behaviour", [#myProp: 15] )
--
-- (3) Setting other parameters after instantiation, and error checking
--
--    result = addScriptToSprite( 10, "My Behaviour" )
--    if( ilk( result, #symbol ) ) then
--      -- The call failed for some reason
--    else
--      result.myProp = 15
--    end if
--
on addScriptToSprite aSprite, aScriptName, aOverridePDL
  
  -- Make sure we are dealing with a sprite
  if( ilk( aSprite, #integer ) ) then
    aSprite = sprite( aSprite )
  else if( not ilk( aSprite, #sprite ) ) then
    return #error_not_a_sprite
  end if
  
  -- Create the script instance
  vScript = script( aScriptName ).rawNew()
  
  -- Add spriteNum and call new()
  vScript.setaProp( #spriteNum, aSprite.spriteNum )
  call( #new, [vScript] )
  
  -- Get defaults from PDL, if applicable
  if( vScript.handler( #getPropertyDescriptionList ) ) then
    
    -- Check PDL override is a list, so we don't get errors
    if( not ilk( aOverridePDL, #propList ) )then
      aOverridePDL = [:]
    end if
    
    -- Get PDL
    vPDL = vScript.getPropertyDescriptionList()
    
    -- Get each default from PDL or override list
    repeat with i = count( vPDL ) down to 1
      vProp = vPDL.getPropAt( i )
      if( ilk( vProp, #symbol ) ) then
        vValue = aOverridePDL.getaProp( vProp )
        if( voidP( vValue ) ) then
          vSet = vPDL.getAt( i )
          if( ilk( vSet, #propList ) ) then
            vValue = vSet.getaProp( #default )
          end if
        end if
        vScript.setaProp( vProp, vValue )
      end if
    end repeat
  end if
  
  -- Add instance to scriptInstanceList
  aSprite.scriptInstanceList.add( vScript )
  
  -- Call beginSprite, if applicable
  call( #beginSprite, [vScript] )

  -- Return the newly created script instance
  return vScript
end