Trackables Script

//===========================================================================
//This simple library defines a trackable. It allows to store information
//about a trackable such as it's position, owner, facing angle, etc and it
//also allows for the user to attach a structure to the trackable. 
//This library also allows to create trackables over a region.
//
//Version 1.2.0
//
//Author:
// - Flame_Phoenix
//
//Requirements:
// - Table from Vexorian
//
//Credits:
// - Kattana, for his tutorial
// - Hans_Maulwurf, for code inspiration, ideas and typo reports
//
//Methods:
//static method advancedCreate takes real x, real y, real facing, string path, player owner, 
//code onTrack, code onClick returns Trackable
// - Create a Trackable object with the given data
//
////static method create takes real x, real y, player owner, 
//code onTrack, code onClick returns Trackable
// - Create a Trackable object with the given data. In this case the default the script will
//use DEFAULT_ANGLE and DEFAULT_PATH to create the trackable.
//
//method onDestroy takes nothing returns nothing
// - trackables cannot be destroyed. However we can disable and destroy the triggers that
//run them, and we can remove the Trackable object from table. This is what this method does.
//
//Members you can use:
//this.x - the X coordinate of the trackable. Has read permissions.
//this.y - the Y coordinate of the trackable. Has read permissions.
//this.facing - the facing angle of the trackable. Has read permissions.
//this.path - the path (model being used) of the tracable. Has read permissions.
//this.tracker - the trackable itself. Has read permissions.
//this.owner - the owner of the trackable. Has read permissions.
//this.data - it can be a structure attached to the Trackable object. Has write and read permissions.
//this.onClickTrgAction - this is the function that runs when you click the trackable. Has write permissions.
//this.onTrackTrgAction - this is the function that runs when you over the trackable. Has write permissions.
//
//Note: to change a member just do "myTrack.data = blablabal"
//Note: to access a member just do "local real myX = myTrack.x"
//
//Functions:
//function CreateTrackedRegion takes rect where, real trackSize, string path, real facing, player owner, 
//code onTrack, code onClick returns nothing
// - This function fills a region with trackables. There is little to say.
//
//function CreateTrackedArea takes real topLeftX, real topLeftY, real width, real height, real trackSize, 
//string path, real facing, player owner, code onTrack, code onClick returns nothing
// - This function does the same thing the previous function does, but it doesn't require a rect. Instead it
//takes the top left corner of the area and then it lets the magic happen.
//
//NOTE: you must be carefull when using functions CreateTrackedRegion and CreatedTrackedArea. If the area or 
//the region to fill is too big, you will hit the oplimit of the thread and the region will be 100% filled
//with trackables.
//
//function GetTrackableData takes trackable whichTrackable returns Trackable
// - this is used to get the information from a trackable. See the example:
//    private function TrackableHit takes nothing returns nothing
//        local Trackable tracker = GetTrackableData(GetTriggeringTrackable())
//        call BJDebugMsg("cliked!")
//        call BJDebugMsg("x = " + R2S(tracker.x))
//        call BJDebugMsg("y = " + R2S(tracker.y))
//    endfunction
//
//===========================================================================
library Trackable initializer Init requires Table
//===========================================================================
//=============================SETUP START===================================
//===========================================================================
    globals 
    //destroying triggers has some obscure effects. In this case I allow it, 
    //but if you think this is causing porblems, just set the boolean valu to false.
    //Know that no matter the value this boolean flag holds, the triggers of a trackable
    //are always disabled when you call onDestroy.
        public constant boolean DESTROY_TRIGGERS = true
        public constant string DEFAULT_PATH = "units\\human\\Peasant\\Peasant.mdl"
        public constant real DEFAULT_ANGLE = 0.
    endglobals
//===========================================================================
//=============================SETUP END=====================================
//===========================================================================
    globals
        private HandleTable activeTable //your private Table's global variable
    endglobals
    
    struct Trackable
        private real tcX
        private real tcY
        private real tcFacing
        private string tcPath = ""
        private trackable track
        private player tcOwner
        private integer tcData
        private trigger onTrackTrg = null
        private trigger onClickTrg = null
        
        static method advancedCreate takes real x, real y, real facing, string path, player owner, code onTrack, code onClick returns Trackable
            local Trackable this = Trackable.allocate()
            
            if GetLocalPlayer() == owner then
                set .tcPath = path 
            endif
            
            set .tcX = x
            set .tcY = y
            set .tcFacing = facing
            set .tcOwner = owner
            set .track = CreateTrackable(.tcPath, .tcX, .tcY, .tcFacing)
            
            if onClick != null then
                set .onClickTrg = CreateTrigger()
                call TriggerRegisterTrackableHitEvent(.onClickTrg, .track)
                call TriggerAddAction(.onClickTrg, onClick)
            endif
            
            if onTrack != null then 
                set .onTrackTrg = CreateTrigger()
                call TriggerRegisterTrackableTrackEvent(.onTrackTrg, .track)
                call TriggerAddAction(.onTrackTrg, onTrack)
            endif

            //save this struct into Table
            set activeTable[.track] = this 
            
            return this
        endmethod
        
        static method create takes real x, real y, player owner, code onTrack, code onClick returns Trackable
            local Trackable this = Trackable.allocate()
            
            if GetLocalPlayer() == owner then
                set .tcPath = DEFAULT_PATH
            endif
            
            set .tcX = x
            set .tcY = y
            set .tcFacing = DEFAULT_ANGLE
            set .tcOwner = owner
            set .track = CreateTrackable(.tcPath, .tcX, .tcY, DEFAULT_ANGLE)
            
            if onClick != null then
                set .onClickTrg = CreateTrigger()
                call TriggerRegisterTrackableHitEvent(.onClickTrg, .track)
                call TriggerAddAction(.onClickTrg, onClick)
            endif
            
            if onTrack != null then 
                set .onTrackTrg = CreateTrigger()
                call TriggerRegisterTrackableTrackEvent(.onTrackTrg, .track)
                call TriggerAddAction(.onTrackTrg, onTrack)
            endif

            //save this struct into Table
            set activeTable[.track] = this 
            
            return this
        endmethod
        
        method onDestroy takes nothing returns nothing
            
            //disable the triggers
            if .onTrackTrg != null then
                call DisableTrigger(.onTrackTrg)
            endif
            
            if .onClickTrg!= null then
                call DisableTrigger(.onClickTrg)
            endif
            
            //the user may not want to destroy the triggers
            if DESTROY_TRIGGERS then 
                if .onTrackTrg != null then
                    call DestroyTrigger(.onTrackTrg)
                endif
                
                if .onClickTrg!= null then
                    call DestroyTrigger(.onClickTrg)
                endif
            endif
            
            //remove trackable from Table
            call activeTable.flush(.track)
        endmethod
        
        //getters
        method operator x takes nothing returns real
            return .tcX
        endmethod
        
        method operator y takes nothing returns real
            return .tcY
        endmethod
        
        method operator facing takes nothing returns real
            return .tcFacing
        endmethod
    
        method operator path takes nothing returns string
            return .tcPath
        endmethod
        
        method operator tracker takes nothing returns trackable
            return .track
        endmethod
        
        method operator owner takes nothing returns player
            return .tcOwner
        endmethod
        
        method operator data takes nothing returns integer
            return .tcData
        endmethod
        
        //setters        
        method operator data= takes integer newData returns nothing
            set .tcData = newData
        endmethod
        
        method operator onClickTrgAction= takes code newFunction returns nothing
            //we get rid of the old trigger
            if .onClickTrg != null then
                call DisableTrigger(.onClickTrg)
                if DESTROY_TRIGGERS then 
                    call DestroyTrigger(.onClickTrg)
                endif
            endif
            
            //create a new one
            set .onClickTrg = CreateTrigger()
            call TriggerRegisterTrackableHitEvent(.onClickTrg, .track)
            
            //register actions
            call TriggerAddAction(.onClickTrg, newFunction)
        endmethod
        
        method operator onTrackTrgAction= takes code newFunction returns nothing
            //we get rid of the old trigger
            if .onTrackTrg != null then
                call DisableTrigger(.onTrackTrg)
                if DESTROY_TRIGGERS then 
                    call DestroyTrigger(.onTrackTrg)
                endif
            endif
            
            //create a new one
            set .onTrackTrg = CreateTrigger()
            call TriggerRegisterTrackableHitEvent(.onTrackTrg, .track)
            
            //register actions
            call TriggerAddAction(.onTrackTrg, newFunction)
        endmethod 
    endstruct
//===========================================================================
    function GetTrackableData takes trackable whichTrackable returns Trackable
        return activeTable[whichTrackable]
    endfunction
//===========================================================================
    private function PlaceTrackables takes real maxX, real minX, real maxY, real minY, real trackSize, string path, real facing, player owner, code onTrack, code onClick returns nothing
        local real currentX = minX 
        local real currentY = minY
        local integer i = 0

        loop
            exitwhen currentY >= maxY
            
            loop
                exitwhen currentX >= maxX
                call Trackable.advancedCreate(currentX, currentY, 0., path, owner, onTrack, onClick)
                set currentX = currentX + trackSize
            endloop

            set currentX = minX 
            set currentY = currentY + trackSize
        endloop
    endfunction
//===========================================================================
    function CreateTrackedArea takes real topLeftX, real topLeftY, real width, real height, real trackSize, string path, real facing, player owner, code onTrack, code onClick returns nothing
        local real maxX = topLeftX + width
        local real maxY = topLeftY
        local real minX = topLeftX
        local real minY = topLeftY - height
        
        call PlaceTrackables(maxX, minX, maxY, minY, trackSize, path, facing, owner, onTrack, onClick)
    endfunction
//===========================================================================
    function CreateTrackedRegion takes rect where, real trackSize, string path, real facing, player owner, code onTrack, code onClick returns nothing
        local real maxX = GetRectMaxX(where)
        local real maxY = GetRectMaxY(where)
        local real minX = GetRectMinX(where)
        local real minY = GetRectMinY(where)
        
        call PlaceTrackables(maxX, minX, maxY, minY, trackSize, path, facing, owner, onTrack, onClick)
    endfunction
//===========================================================================
    private function Init takes nothing returns nothing
        //setting our globals
        set activeTable = HandleTable.create() //Create our spell's private Table for casters
    endfunction
endlibrary

        private trigger onTrackTrg = CreateTrigger()
        private trigger onClickTrg = CreateTrigger()

if GetLocalPlayer() == owner then
     set .tcPath = path 
endif