ItemHoldupMessage.zh v1.1 for ZC 2.54+

///////////////////////////
/// Item Hold Up Header ///
/// v1.1 for ZC 2.54+   ///
/// 2nd August, 2017    ///
/// By: ZoriaRPG        ///
///////////////////////////

//!!!!!!!!!!!!!!!!!!!!!
//! Settings

const int ITEM_HOLDUP_ZH__DEFAULT_LA_HOLDUP_HANDS = 1; //The number of hands to use for the default hold-up animation.
const int ITEM_HOLDUP_ZH__DEFAULT_SFX_HOLD_ITEM_FANFARE = 20; //Change to the sound that you want.
const int ITEM_EDITOR_ATTRIBUTES_HOLDUP_HANDS = 7; //THis will be deprecated by an item editor value for holdup type.
const int ITEM_EDITOR_ATTRIBUTES_FANFARE_SFX = 8;
const int ITEM_EDITOR_ATTRIBUTES_PICKUP_MESSAGE = 9;


//!!!!!!!!!!!!!!!!!!!!!
//! Scripts

item script PickMessageFFCLauncher
{
    void run()
        //Set up some defaults.

        if
        (
            ( this->Attributes[ITEM_EDITOR_ATTRIBUTES_HOLDUP_HANDS < 1 )
                || ( this->Attributes[ITEM_EDITOR_ATTRIBUTES_HOLDUP_HANDS > 2 )
        )
        {
            this->Attributes[ITEM_EDITOR_ATTRIBUTES_HOLDUP_HANDS] = ITEM_HOLDUP_ZH__DEFAULT_LA_HOLDUP_HANDS;
        }
        if
        (
            ( this->Attributes[ITEM_HOLDUP_ZH__DEFAULT_SFX_HOLD_ITEM_FANFARE < 1 )
                || ( this->Attributes[ITEM_HOLDUP_ZH__DEFAULT_SFX_HOLD_ITEM_FANFARE > MAX_SFX )
        )
        {
            this->Attributes[ITEM_HOLDUP_ZH__DEFAULT_SFX_HOLD_ITEM_FANFARE] = ITEM_HOLDUP_ZH__DEFAULT_SFX_HOLD_ITEM_FANFARE;
        }
        int foundff; //Used to determine if there is no matching script ID, and to suply an error.
                //Otherwise it is the ID of the 'free' ffc (screen index).
        int _____ffscript_id; //Holds the script ID, to pass to functions.


        if ( Link->Action == LA_DIVING )
        {
            _____ffscript_id = Game->GetFFCScript("FFC_DiveHoldUp");
            if ( _____ffscript_id < 1 )
            {   //Error and exit if the ffc script is not in the quest matrix.
                ItemHoldupZH_FFC_Failure_Error("FFC_DiveHoldUp", "Aborting item hold-up.");
                Quit();
            }
        }
        else if ( Link->Action == LA_SWIMMING  )
        {
            _____ffscript_id = Game->GetFFCScript("FFC_SwimHoldUp");
            if ( _____ffscript_id < 1 ) {
                //Error and exit if the ffc script is not in the quest matrix.
                ItemHoldupZH_FFC_Failure_Error("FFC_SwimHoldUp", "Aborting item hold-up.");
                Quit();
            }
        }
        else
        {
            //Link is on land.
            _____ffscript_id = Game->GetFFCScript("FFC_ItemHoldUp");
            if ( _____ffscript_id < 1 ) {
                //Error and exit if the ffc script is not in the quest matrix.
                ItemHoldupZH_FFC_Failure_Error("FFC_ItemHoldUp", "Aborting item hold-up.");
                Quit();
            }
        }

        foundff = ItemHoldup_FindFreeFFC(); //Grab a free ffc.

        if ( foundff > 0 && foundff < 33 )
        {   //if we find one, set it up to use the correct script.
            ItemHoldUp_SetUpFFC(foundff, _____ffscript_id, this->ID,
            this->Attributes[ITEM_EDITOR_ATTRIBUTES_PICKUP_MESSAGE]),
            this->Attributes[ITEM_EDITOR_ATTRIBUTES_FANFARE_SFX], this->Attributes[ITEM_EDITOR_ATTRIBUTES_HOLDUP_HANDS];

        }
        if ( foundff <= 0  )
        {
            //Error if we cannot grab a free ffc.
            TraceNL(); TraceS("Cound not find a free ffc slot to run the ffc script for item script PickMessageFFCLauncher. ");
            Trace("Aborting item hold-up."); TraceNL();
        }
        Quit();


    }
    int ItemHoldup_FindFreeFFC()
    {
        for ( int q = 32; q > 0; q-- )
        {
            ffc f = Screen->LoadFFC(q);
            if ( f->Data == 0 )
            {
                if ( f->Script == 0 )
                return q;
            }
        }
        return -1;
    }
    void ItemHoldUp_SetUpFFC(int screen_ff_index, int ffscript_id, int ________initD0, int ________initD1, int ________initD2, int ________initD3)
    {

        ffc f = Screen->LoadFFC(screen_ff_index);
        f->Data = 1;
        f->Script = ffscript_id;
        f->InitD[0] = ________initD0;
        f->InitD[1] = ________initD1;
        f->InitD[0] = ________initD2;
        f->InitD[1] = ________initD3;

    }
    void ItemHoldupZH_FFC_Failure_Error(int a, int b)
    {   //a == ff, b == ___err_aborting
        TraceNL(); TraceS("Cound not find the script: "); TraceS(a); TraceNL(); TraceS(b); TraceNL();
    }

}

////////////////////////////////////////////////////////////////////
/// FFC Scripts
/// These drive the effects for item hold-up and message display,
/// and are called automatically by the launcher.
/// DO NOT PLACE THESE ON A SCREEN!

ffc script FFC_SwimHoldUp{
    void run(int itm, int __item_message_string, int ___sound, int ___holduphands)
    {
        Waitframe();    // An initial waitframe so that the item pick-up script is fully closed,
                // and so that the item collect script  effects finish running before
                // we do anything else.

        if ( ___sound > 0 && ___sound < 255)
        {
            Game->PlaySound(___sound);
        }
        Link->Action = LA_HOLD1WATER + (___holduphands-1);
        Link->HeldItem = itm;
        //do-while loop to delay the message display until the hold-up animation eneds.
        do{
            Waitframe();
        } while( Link->Action == LA_HOLD1WATER || Link->Action == LA_HOLD2WATER );
        Screen->Message(__item_message_string);
        this->Data = 0;
        this->Script = 0;
        Quit();
    }
}

ffc script FFC_DiveHoldUp{
    void run(int itm, int __item_message_string)
    {

        do {
            Waitframe();
        } while(Link->Action == LA_DIVING);

        do {
            Waitframe();
        } while( Link->Action == LA_HOLD1WATER || Link->Action == LA_HOLD2WATER );

        //ZC Automatically Holds Up all dive items, and plays the Item Fanfare SFX (SFX: 20, hardcoded).

        Screen->Message(__item_message_string);
        this->Data = 0;
        this->Script = 0;
        Quit();
    }
}


ffc script FFC_ItemHoldUp{
    void run(int itm, int __item_message_string, int ___sound, int ___holduphands)
    {

        Link->Action = LA_HOLD1LAND + (___holduphands-1);
        Link->HeldItem = itm;
        if ( ___sound > 0 && ___sound < 255)
        {
            Game->PlaySound(___sound);
        }

        // This do-while loop is to ensure that the message does not obscure the item during the hold-up animation.
        do {
            Waitframe();
        } while(Link->Action == LA_HOLD1LAND || Link->Action == LA_HOLD2LAND);

        Screen->Message(__item_message_string);
        this->Data = 0;
        this->Script = 0;
        Quit();
    }
}
//Maddening, isn't it? -Z