Difference between revisions of "Verbcoin (module)"

From Adventure Game Studio | Wiki
Jump to navigationJump to search
*>Monkey 05 06
m (→‎Downloads: Fixed list being all dumb and one of the links.)
m
 
Line 37: Line 37:
 
===Help and Support===
 
===Help and Support===
  
If you need further help or support beyond the included documentation, contact {{link|monkey_05_06|me}} by posting in {{forum|args=topic=42868.0|name=the Verbcoin module thread}} on the forums.
+
If you need further help or support beyond the included documentation, contact {{link|monkey_05_06|me}} by posting in {{thread|the Verbcoin module thread|42868.0}} on the forums.
  
 
===Getting started with the Verbcoin module===
 
===Getting started with the Verbcoin module===

Latest revision as of 06:05, 19 August 2012

This page is about the Verbcoin (module)/template by monkey_05_06. For other uses of Verbcoin see Verbcoin.

Contents

Verbcoin Module/Template

The Verbcoin module (also included in the Verbcoin template) provides a generic framework for implementing a Verbcoin (interface) in your game.

Downloads

Latest Versions

Verbcoin template v1.1 (For AGS 3.1.1+) (Includes module v1.1)

Verbcoin module v1.1 (For AGS 3.0+)

Verbcoin demo v1.0a (Includes module v1.0a, but not template) (This is the same as the compiled version of the template v1.0a)

Compatibility Versions

Verbcoin template v1.0c (For AGS 3.0+) (No native coordinates, uses low-res coordinates*) (Includes module v1.0b)

Verbcoin template v1.0a (For AGS 3.1+) (No "normal" dialog scripting, uses run-script*) (Includes module v1.0a)


*This shouldn't make any difference in your own game if using a higher version of AGS, and would then only to the template files themselves.

Older Versions

Verbcoin template v1.0b (For AGS 3.1.1+) (Includes module v1.0a)

Verbcoin module v1.0b (For AGS 3.0+)

Verbcoin template v1.0 (Requires AGS 3.2.1+)

Verbcoin module v1.0 (Requires AGS 3.2+)

Verbcoin demo v1.0 (Includes module v1.0)

Help and Support

If you need further help or support beyond the included documentation, contact me by posting in the Verbcoin module thread on the forums.

Getting started with the Verbcoin module

Getting started with the Verbcoin module is relatively simple. Import the module into your project, and set up your GUI however you would like. We'll use Button controls to determine where our "verbs" are at, so be sure that you add these controls where appropriate. Once you've got that taken care of, you'll need to add a few lines to your script to finish setting up the interface.

Example:

 // GlobalScript.asc
 
 function game_start()
 {
   Verbcoin.CoinGUI = gVerbcoin; // tell the module which GUI we will be using for our verbcoin
   Verbcoin.XOffset = gVerbcoin.Width / 2; // set the offset for displaying our GUI
   Verbcoin.YOffset = gVerbcoin.Height / 2; // here we'll just centre it
   Verbcoin.AddButton(btnLook, "Look at", eModeLookat); // add our buttons that the verbcoin will use
   Verbcoin.AddButton(btnTalk, "Talk to", eModeTalkto); // we tell the module what text we want associated with the button
   Verbcoin.AddButton(btnUse, "Use", eModeInteract); // as well as what CursorMode we want to associate the button with
 }

And that's it! This is a fairly basic setup for a verbcoin interface, with three buttons for Look, Talk, and Use. There are other settings that you may want to look at such as Verbcoin.DefaultMode or Verbcoin.Delay, but this should be enough to get you started. A full function list, complete with example code, is provided below.

Enumerated values and macros

VerbcoinSettings

eVerbcoinDefaultButtonCount

Sets the number of buttons to allocate memory for at the start of the game. You may add or remove buttons at runtime, but the closer this is to your initial GUI configuration the less impacting it will be on the start of your game.

eVerbcoinDefaultDelay

Sets the default number of game loops used to determine if the user is holding the mouse down, or has double-clicked, after an initial mouse-click.

eVerbcoinMaxStateSavingRooms

Sets the maximum number of rooms the module will persist data for. Other rooms will be able to take advantage of all module functions, but any data from those rooms will be purged when the next room is loaded.

Verbcoin_VERSION

Defines the current version of the module, formatted as a float.

Verbcoin_VERSION_110

Defines version 1.1 of the module.

Verbcoin_VERSION_100

Defines version 1.0 of the module.

Verbcoin_UnhandledEventHandler

This macro is NOT defined by the module, but it is used if it is defined. See the section below for more information on how this macro is defined and used.

About the Verbcoin_UnhandledEventHandler macro

The Verbcoin_UnhandledEventHandler macro is one that is not actually defined by the module, yet is provided to help future-proof the module's UnhandledEvent function. The module provides the function Verbcoin.UnhandledEvent which is automatically called by the built-in AGS unhandled_event function, and can be called by the user as needed. However, since the function belongs to the Verbcoin struct, and it is used internally within the module, this function has to be defined within the module script.

This isn't necessarily a problem for the module author, but for the end-user it could potentially pose a problem in the future. If you manually edit the Verbcoin.asc module script file to include your own interactions for unhandled events, and then later were to upgrade to a newer version of the Verbcoin module, you would lose the modifications you had made to the module scripts! That's where the Verbcoin_UnhandledEventHandler macro comes in.

As we already said, this macro is not defined by the module, so how then do you make use of it? This particular macro is one that you, the user must define to take advantage of it. It is provided with the idea that you're going to be adding your interactions in a separate script. For the purposes of an example, we'll assume that you have a script, above the Verbcoin script, called "UnhandledEvent". We'll take a look at what you would want to put in that script to give you an idea of how this macro is used.

First we'll set up a function in UnhandledEvent.asc where we will actually define our interactions:

 // UnhandledEvent.asc
 
 void UnhandledEventHandler(CursorMode mode, LocationType locType, InventoryItem *theItem)
 {
   if (mode == eModeInteract)
   {
     player.Say("I can't use that.");
   }
   else if (mode == eModeLookat)
   {
     player.Say("I don't see what's so special about it.");
   }
   else if (mode == eModePickup)
   {
     player.Say("I can't pick that up!");
   }
   else if (mode == eModeTalkto)
   {
     player.Say("I can't talk to that.");
   }
   else if (mode == eModeUseinv)
   {
     if (player.ActiveInventory != null)
     {
       if (theItem == null) player.Say("I can't use the %s on that.", player.ActiveInventory.Name);
       else player.Say("I can't use the %s on the %s.", player.ActiveInventory.Name, theItem.Name);
     }
     else player.Say("I can't use that.");
   }
 }

Note that the parameter list for our new function is the same as Verbcoin.UnhandledEvent. If you would like to add any additional parameters to this function you can, but they MUST be optional if you do, and these first three parameters MUST be the same. Since we've defined this function in UnhandledEvent.asc, upgrading the Verbcoin module will no longer mean losing our interactions for unhandled events.

Now that we've established our interactions, we need to link these functions together. This is where we actually get around to defining the macro:

 // UnhandledEvent.ash
 
 #define Verbcoin_UnhandledEventHandler UnhandledEventHandler // $AUTOCOMPLETEIGNORE$
 import void Verbcoin_UnhandledEventHandler(CursorMode, LocationType, InventoryItem*=0);

This is a little more complex than your typical macro, so I'll try to help you understand what's going on here. We define the macro to have the value of UnhandledEventHandler. This is the name of the function we defined previously. What this means is that any time we type Verbcoin_UnhandledEventHandler, AGS is going to instead see the name of our function, UnhandledEventHandler. The comment $AUTOCOMPLETEIGNORE$ is a special tag that tells the autocomplete to ignore this line in our script. We don't actually want the macro itself showing up in the autocomplete list.

The second line is a normal function import, but with a couple things that we're going to look at. We're importing the function Verbcoin_UnhandledEventHandler, but we haven't defined a function with that name anywhere! But remember, the macro is telling AGS that what we really mean is UnhandledEventHandler, which is a function that we've defined already. So, thanks to the macro, we're really importing our function that we defined in the script. I also want to point out that the InventoryItem parameter is made optional by setting it equal to 0. Normally you can't use integer values like 0 with pointers, but when we're importing a function we are allowed to use the value of 0 as a substitute for null.

And that's it. With that set up, the module can now call your custom function automatically when appropriate. This macro allows the module to check whether you have defined a custom function for processing these unhandled events. Either way the module function will still be called by the built-in AGS function.

Global functions and properties

Verbcoin functions

Verbcoin.ActionText

readonly String Verbcoin.ActionText

Returns the interaction text of the selected verb button for the item last clicked on. This is useful in conjunction with LocationName for display on a label. If the verbcoin is not shown or the mouse is not over one of the used buttons, this returns null.

Example:

 lblLocation.Text = String.Format("%s %s", Verbcoin.ActionText, Verbcoin.LocationName);

That would set the text on the label to the current action and location. So if you had clicked on Roger and had the mouse over the "Look at" button then the text on the label would be "Look at Roger". Keep in mind that this may be null, so you would want to check that before using it.

See Also: Verbcoin.ActiveInventoryActionFormat, Verbcoin.ButtonActionText, Verbcoin.LocationName, GetActionText functions, SetActionText functions

Verbcoin.ActiveInventoryActionFormat

String Verbcoin.ActiveInventoryActionFormat

Used to get or set the format string for when the player has an active inventory item. This format should contain one "%s" modifier to have the name of the inventory item inserted. You won't normally need to read this value once it's set as the ActionText will be properly updated when there is an active inventory item. The default value is simply "Use %s with".

Example:

 Verbcoin.ActiveInventoryActionFormat = "Give %s to";

This would change the formatting of the ActionText when there is an active inventory item. This particular example might be useful if the mouse is over a Character.

See Also: Verbcoin.ActionText

Verbcoin.AddButton

bool Verbcoin.AddButton(Button*, String actionText, CursorMode)

Attempts to add the specified button to the verbcoin with the given interaction text and mouse mode. This can fail if the CoinGUI isn't set yet or an invalid button is specified. Returns true upon success, false upon failure.

Example:

 Verbcoin.AddButton(btnLook, "Look at", eModeLookat);

You might do this to set up your GUI in game_start, or if you add more options later in the game.

See Also: Verbcoin.ButtonCount, Verbcoin.Buttons, Verbcoin.CoinGUI, Verbcoin.MaxButtonCount, Verbcoin.RemoveButton

Verbcoin.ButtonActionText

String Verbcoin.ButtonActionText[int index]

Used to get or set the interaction text for the button at INDEX. This is the default action that will be supplied to ActionText when the mouse is over this button. To determine which INDEX you need for a given button, use GetButtonID.

Example:

 int bID = Verbcoin.GetButtonID(btnLook);
 Verbcoin.ButtonActionText[bID] = "Examine";

This changes the text supplied when the button was added to the Verbcoin to "Examine".

See Also: Verbcoin.ActionText, Verbcoin.AddButton, Verbcoin.ButtonCount, Verbcoin.ButtonMode, Verbcoin.Buttons, Verbcoin.GetButtonID, Verbcoin.SetButtonActionText, GetActionText functions, SetActionText functions

Verbcoin.ButtonCount

readonly int Verbcoin.ButtonCount

Returns the number of buttons currently in use by the verbcoin. This can help you determine whether or not you can add more buttons to the verbcoin, as well as giving the size of the Button arrays.

Example:

 int i = 0;
 while (i < Verbcoin.ButtonCount)
 {
   Display("Button\[%d] action: %s", i, Verbcoin.ButtonActionText[i]);
   i++;
 }

This would display the interaction text for every button currently in-use by the module.

See Also: Verbcoin.AddButton, Verbcoin.ButtonActionText, Verbcoin.ButtonMode, Verbcoin.Buttons, Verbcoin.MaxButtonCount, Verbcoin.RemoveButton

Verbcoin.ButtonMode

CursorMode Verbcoin.ButtonMode[int index]

Used to get or set the interaction mode for the button at INDEX. This is the mode that will be used when the mouse is released over the button on the verbcoin. To determine which INDEX you need for a given button, use GetButtonID.

Example:

 int bID = Verbcoin.GetButtonID(btnLook);
 Verbcoin.ButtonMode[bID] = eModeUsermode1;

This changes all future uses of btnLook on the verbcoin to use eModeUsermode1.

See Also: Verbcoin.ButtonActionText, Verbcoin.ButtonCount, Verbcoin.Buttons, Verbcoin.GetButtonID, Verbcoin.SetButtonMode

Verbcoin.Buttons

readonly Button* Verbcoin.Buttons[int index]

Returns the button at the specified INDEX from those currently in use by the verbcoin. These cannot be set directly since they are directly tied to both the interaction text and mode. To get the index for a given button, use GetButtonID instead.

Example:

 if (Verbcoin.Buttons[2] == btnLook) Display("btnLook is at index 2!");

Of course you would probably want to use GetButtonID for this instead anyway.

See Also: Verbcoin.AddButton, Verbcoin.ButtonActionText, Verbcoin.ButtonCount, Verbcoin.ButtonMode, Verbcoin.GetButtonID, Verbcoin.RemoveButton

Verbcoin.ClickedX

readonly int Verbcoin.ClickedX

Returns the X coordinate of the last mouse-click registered by the module. You won't normally need this, and it will be reset to -1 when not in use by the module.

Example:

 Display("Clicked at (%d,%d)!", Verbcoin.ClickedX, Verbcoin.ClickedY);

Would display the coordinates of the last click. As noted however, this isn't really a practical example, but you might be able to find some use of the information.

See Also: Verbcoin.ClickedY

Verbcoin.ClickedY

readonly int Verbcoin.ClickedY

Returns the Y coordinate of the last mouse-click registered by the module. You won't normally need this, and it will be reset to -1 when not in use by the module.

Example:

 Display("Clicked at (%d,%d)!", Verbcoin.ClickedX, Verbcoin.ClickedY);

Once again, you might be able to find some reason to want this information, but you probably shouldn't need it.

See Also: Verbcoin.ClickedX

Verbcoin.CoinGUI

GUI* Verbcoin.CoinGUI

Used to get or set the GUI used as the "coin" of the verbcoin. This GUI must be the OwningGUI of any Buttons that you want to use on the verbcoin.

Example:

 Verbcoin.CoinGUI = gVerbcoin;

You would do something like this in game_start to set up your GUI for the first time, and of course it can be changed at runtime if needed.

NOTE: Since all interaction text and mouse modes are linked to their respective Button controls, if the CoinGUI is changed at runtime, ALL of this information will be LOST. If you are using more than one GUI in your game, consider this carefully when setting up your game. You may want to just rearrange the existing GUI, or possibly use a custom function to switch between the GUIs.

See Also: Verbcoin.AddButton, Verbcoin.RemoveButton, Verbcoin.XOffset, Verbcoin.YOffset

Verbcoin.DefaultMode

CursorMode Verbcoin.DefaultMode

Used to get or set the default interaction mode, when the mouse is just clicked instead of held. The default value for this is eModeWalkto.

Example:

 Verbcoin.DefaultMode = eModeInteract;

Changes the normal interaction mode to eModeInteract.

See Also: Verbcoin.Delay

Verbcoin.Delay

int Verbcoin.Delay

Gets or sets the delay used in determining whether the mouse is held down, or double-clicked, after a mouse-click.

Example:

 Verbcoin.Delay = GetGameSpeed() / 4;

Sets the delay to 1/4 of a second.

NOTE: Verbcoin functions may be intercepted by Game.IgnoreUserInputAfterTextTimeoutMs. This is NOT a bug in the module, but is rather by design.

See Also: Verbcoin.DoubleClicked

Verbcoin.DoubleClicked

readonly bool Verbcoin.DoubleClicked

Returns whether the user clicked the mouse twice within the specified delay time.

Example:

 if (Verbcoin.DoubleClicked)
 {
   Verbcoin.IgnoreLastClickOrDoubleClick();
   // ..do something else here..
 }

That would override the normal module handling of the mouse-click, providing you the opportunity to do something else with the double-click.

NOTE: The Verbcoin module does NOT, by default, provide any "default interaction" methods for use with a double-click. If you want to do something with a double-click, this is provided so you can use it as you wish, but there is nothing built-in of this nature.

NOTE: By default double-clicking is treated the same as single-clicking twice. You must set Verbcoin.UseDoubleClicks yourself if you want this to ever return true.

NOTE: Prior to Verbcoin v1.1 this value would only return true ONCE per double-click. After it has returned true, the value would be cleared. If you are using v1.0 of the module, be sure to store this value separately if you need to use it more than once per double-click.

NOTE: Prior to Verbcoin v1.1 you had to call IgnoreLastClickOrDoubleClick to prevent a double-click from being processed as two single-clicks (even if double-clicks were enabled). You no longer have to call this function to stop the single- clicks from being processed, but this value will remain set to true until the function is called.

See Also: Verbcoin.Delay, Verbcoin.IgnoreLastClickOrDoubleClick, Verbcoin.UseDoubleClicks

Verbcoin.Enabled

bool Verbcoin.Enabled

Used to enable or disable the verbcoin module functions. This can be useful if you want to temporarily disable the verbcoin.

Example:

 Verbcoin.Enabled = false;

This disables the module functions without purging any of the module data.

Verbcoin.GetButtonID

int Verbcoin.GetButtonID(Button*)

Returns the index for the specified button that can be used with the Button arrays, or -1 if the button is not in-use by the module.

Example:

 int bID = Verbcoin.GetButtonID(btnLook);
 Verbcoin.ButtonActionText[bID] = "Examine";

Changes the interaction text for btnLook to "Examine".

See Also: Verbcoin.ButtonActionText, Verbcoin.ButtonCount, Verbcoin.ButtonMode, Verbcoin.Buttons

Verbcoin.Hotspot0Name

String Verbcoin.Hotspot0Name

Used to get or set the name, as used by LocationName, for hotspot 0. By default this is set to null and is not used. The value is reset upon entering a new room, or if IgnoreHotspot0 is set to true.

Example:

 Verbcoin.Hotspot0Name = "nothing";

This would set the name to "nothing" so that whenever the mouse is over hotspot 0 (but not over anything else such as a character or object) then LocationName would be set to "nothing".

See Also: Verbcoin.IgnoreHotspot0, Verbcoin.LocationName

Verbcoin.IgnoreHotspot0

bool Verbcoin.IgnoreHotspot0

Used to control whether hotspot 0 is ignored by the module. If this is true then the verbcoin will not be activated by clicking on hotspot 0 at all; otherwise hotspot 0 will be treated as a normal hotspot. This value is automatically updated if Hotspot0Name is changed (if Hotspot0Name is set to null then this is set to true, any other value for Hotspot0Name will set this to false).

Example:

 Verbcoin.IgnoreHotspot0 = false;
 Verbcoin.Hotspot0Name = "nothing";

This will enable the usage of hotspot 0 by the module, and update the name to use for the hotspot. Since this value is automatically updated, this isn't a necessary step.

Verbcoin.IgnoreInventoryClicks

bool Verbcoin.IgnoreInventoryClicks

Used to get or set whether the module should ignore clicks on the inventory. By default, inventory items are treated the same as characters, objects, and hotspots with regards to the verbcoin functions (meaning, you use the verbcoin to interact with them). You can use this value if you want to handle inventory clicks a different way (without the verbcoin).

Example:

 Verbcoin.IgnoreInventoryClicks = true;

This would tell the module to ignore any mouse-clicks on an inventory item, so that you could process it yourself.

Compatibility: Supported by Verbcoin v1.1 and higher.

Verbcoin.IgnoreLastClickOrDoubleClick

void Verbcoin.IgnoreLastClickOrDoubleClick()

Tells the module to ignore the last click or double-click, and cancels any module processing of it. This might be useful if you want to use double-clicks for something, since the module does not provide any methods for using them.

Example:

 if (Verbcoin.DoubleClicked)
 {
   Verbcoin.IgnoreLastClickOrDoubleClick();
   // ..do something here..
 }

How you might want to use double-clicks is up to you, but this function will override the verbcoin functions for you.

NOTE: Prior to Verbcoin v1.1 you had to call this function to prevent a double-click from being processed as two single- clicks (even if double-clicks were enabled). You no longer have to call this function to stop the single-clicks from being processed, but DoubleClicked will remain set to true (for double-clicks) until this function is called.

See Also: Verbcoin.DoubleClicked, Verbcoin.Enabled, Verbcoin.UseDoubleClicks

Verbcoin.LocationName

readonly String Verbcoin.LocationName

Returns the name of whatever the mouse is over. If the mouse-button is held down and the verbcoin is displayed, then this will display the name of what the user clicked on.

Example:

 if (Verbcoin.ActionText == null) lblLocation.Text = Verbcoin.LocationName;
 else lblLocation.Text = String.Format("%s %s", Verbcoin.ActionText, Verbcoin.LocationName);

This would update the text on the label to show the current action and location.

See Also: Verbcoin.ActionText

Verbcoin.MaxButtonCount

readonly int Verbcoin.MaxButtonCount

Returns the maximum number of buttons that the module supports using at once. This is determined partially by the number of characters and inventory items in your game, the value of AGS_MAX_HOTSPOTS, and the value of AGS_MAX_OBJECTS. Additionally, this value will never be higher than AGS_MAX_CONTROLS_PER_GUI since all the buttons must be on the CoinGUI.

Example:

 if (Verbcoin.ButtonCount < Verbcoin.MaxButtonCount) Verbcoin.AddButton(btnTalk, "Talk to", eModeTalkto);

Of course you don't need to check this yourself normally as the AddButton function will simply return false if there are too many buttons in use.

See Also: Verbcoin.AddButton, Verbcoin.ButtonCount, Verbcoin.Buttons, Verbcoin.RemoveButton

Verbcoin.MouseButtonToUse

MouseButton Verbcoin.MouseButtonToUse

Used to get or set which MouseButton you want to use to activate the Verbcoin. The default is eMouseLeft.

Example:

 Verbcoin.MouseButtonToUse = eMouseRight;

This would set the module to use the right mouse button for the verbcoin instead of the left.

Compatibility: Supported by Verbcoin v1.1 and higher.

Verbcoin.RemoveButton

bool Verbcoin.RemoveButton(Button*)

Removes the specified button from the verbcoin. This also removes any interaction text associated with the button, so just keep that in mind. Returns false if the verbcoin was not using the button, or true if it was removed.

Example:

 Verbcoin.RemoveButton(btnTalk);

This would remove the btnTalk button from the verbcoin. Useful, perhaps, if your player gets his mouth removed.

See Also: Verbcoin.AddButton

Verbcoin.SetButtonActionText

bool Verbcoin.SetButtonActionText(Button*, String actionText)

Changes the interaction text for the specified button to ACTIONTEXT. This is used when you want to permanently change the default value for the button. If you instead want to supply an alternate value for a Character, Object, etc. then use the SetActionText functions instead.

Example:

 Verbcoin.SetButtonActionText(btnLook, "Examine");

Changes the action text for btnLook to "Examine".

NOTE: You can do this for buttons already in-use by the verbcoin by setting ButtonActionText directly. This function will add a button that is not already in-use to the verbcoin. For adding buttons it is recommended however that you use AddButton instead since that will allow you to specify the button mode at the same time.

See Also: Verbcoin.AddButton, Verbcoin.ButtonActionText, Verbcoin.SetButtonMode

Verbcoin.SetButtonMode

bool Verbcoin.SetButtonMode(Button*, CursorMode)

Changes the interaction mode for the specified button. This is the mode that will be processed when the mouse is released over the button on the verbcoin.

Example:

 Verbcoin.SetButtonMode(btnTalk, eModeUsermode1);

Changes the cursor mode for btnTalk to eModeUsermode1.

NOTE: You can do this for buttons already in-use by the verbcoin by setting ButtonMode directly. This function will add a button that is not already in-use to the verbcoin. For adding buttons it is recommended however that you use AddButton instead since that will allow you to specify the action text at the same time.

See Also: Verbcoin.AddButton, Verbcoin.ButtonMode, Verbcoin.SetButtonActionText

Verbcoin.UnhandledEvent

void Verbcoin.UnhandledEvent(CursorMode, LocationType, optional InventoryItem*)

Processes an unhandled interaction. The CursorMode and LocationType determine what type of interaction, and with what. The optional InventoryItem parameter is used if LocationType is eLocationNothing but the mouse was over an InventoryItem. This function will automatically be called via the built-in AGS unhandled_event, and comes with some generic default responses.

If you want to specify your own interactions, it is recommended NOT to change the module code, but to use the Verbcoin_UnhandledEventHandler macro instead. Read about that macro for more information on how it is used. Using the macro will prevent you losing your code if you ever upgrade to a higher version of the Verbcoin module.

Example:

 Verbcoin.UnhandledEvent(eModeUseinv, eLocationNothing, InventoryItem.GetAtScreenXY(mouse.x, mouse.y);

This would process the assigned interactions for an otherwise unhandled usage of an active inventory item on another inventory item. Of course, this would already be handled automatically, but you can call the function yourself if you need it, for example if you are using keyboard controls to simulate using the mouse.

Verbcoin.UseDoubleClicks

bool Verbcoin.UseDoubleClicks

Used to get or set whether double-clicks of the mouse should be detected. This is FALSE by default as double-clicks are not used by the module. If this is false, then DoubleClicked will never be true.

Example:

 Verbcoin.UseDoubleClicks = true;

Activates detection of double-clicks. Again, double-clicks are not used by the module, but you must set this value if you want to make use of DoubleClicked.

See Also: Verbcoin.DoubleClicked

Verbcoin.XOffset

int Verbcoin.XOffset

Used to get or set the x-offset of the coin GUI. This is used to position the GUI, relative to the position of where you last clicked.

Example:

 Verbcoin.XOffset = Verbcoin.CoinGUI.Width / 2;
 Verbcoin.YOffset = Verbcoin.CoinGUI.Height / 2;

This would position the coin GUI to be directly centred around the point at which you click the mouse.

See Also: Verbcoin.CoinGUI, Verbcoin.YOffset

Verbcoin.YOffset

int Verbcoin.YOffset

Used to get or set the y-offset of the coin GUI. This is used to position the GUI, relative to the position of where you last clicked.

Example:

 Verbcoin.XOffset = Verbcoin.CoinGUI.Width / 2;
 Verbcoin.YOffset = Verbcoin.CoinGUI.Height / 2;

This would position the coin GUI to be directly centred around the point at which you click the mouse.

See Also: Verbcoin.CoinGUI, Verbcoin.XOffset

GetActionText functions

Character.GetActionText

String Character.GetActionText(Button*)

Hotspot.GetActionText

String Hotspot.GetActionText(Button*)

InventoryItem.GetActionText

String InventoryItem.GetActionText(Button*)

Object.GetActionText

String Object.GetActionText(Button*)

These four extender methods are provided by the module so that you can retrieve the appropriate action text for the given item. If the specified button is not in-use by the module then this will return null; otherwise if there is a custom value given for the specified item, that custom value will be returned. If the button is valid but no custom value has been supplied, this function will return the default action text for the given button.

Example:

 Display(player.GetActionText(btnLook));

This would display the action text associated with the player character for the btnLook button.

See Also: Verbcoin.ActionText, Verbcoin.ButtonActionText, Verbcoin.SetButtonActionText, SetActionText functions

SetActionText functions

Character.SetActionText

void Character.SetActionText(Button*, String actionText)

Hotspot.SetActionText

void Hotspot.SetActionText(Button*, String actionText)

InventoryItem.SetActionText

void InventoryItem.SetActionText(Button*, String actionText)

Object.SetActionText

void Object.SetActionText(Button*, String actionText)

These four extender methods are provided by the module so that you can set custom interaction text for individual items. If the specified button is not in-use by the module then this function is ignored. To disable the custom interaction text and use the default instead, simply pass null as the second parameter.

Example:

 iCracker.SetActionText(btnTalk, "Taste");

Changes the interaction text for the iCracker inventory item to "Taste". This doesn't affect the default interaction text, so other items will still use "Talk to" as the action text, unless they have a custom value supplied.

See Also: Verbcoin.ActionText, Verbcoin.ButtonActionText, Verbcoin.SetButtonActionText, GetActionText functions

Advanced functions

In addition to the functions listed above, there are some functions provided that are intended for ADVANCED users ONLY. If you are not familiar with scripting in AGS, it is recommended that you do not use these functions as they are not typically required for use. These functions should not cause major issues if you do use them, but they can create problems if you don't understand what they are for. For these reasons, these functions will NOT appear in autocomplete.

Verbcoin.AllocateButtonMemory

void Verbcoin.AllocateButtonMemory(int buttonCount)

Attempts to allocate memory for BUTTONCOUNT buttons. If BUTTONCOUNT is less than the number of buttons for which memory is already allocated, this function is ignored. This will not allocate memory for more than MaxButtonCount buttons, though if BUTTONCOUNT is higher than this, it will be adjusted appropriately. This function is provided because it is faster to reallocate any existing memory once than to have to resize the arrays several times.

This function is automatically called by the module with the value of eVerbcoinDefaultButtonCount. You should try to set that enumerated value as close as possible to the actual MAXIMUM number of buttons you will use on your verbcoin in-game. Setting this number too high will only use up system resources unnecessarily, but setting it too low will cause slower processing when the buttons are actually added to your verbcoin.

Example:

 Verbcoin.AllocateButtonMemory(6);

If you wanted to have a total of 6 buttons on your verbcoin GUI, this would allocate the memory for all 6 buttons at once.

NOTE: Even if you do not use this function, you can still add more buttons at runtime, up to MaxButtonCount. The purpose of this function is to prevent having to reallocate the existing memory multiple times when the buttons are added.

See Also: Verbcoin.AddButton, Verbcoin.MaxButtonCount, Verbcoin.RemoveButton, Verbcoin.DeallocateButton, Verbcoin.DeallocateButtonMemory

Verbcoin.DeallocateButton

bool Verbcoin.DeallocateButton(Button*)

Attempts to remove a button from the verbcoin, and deallocate any memory associated with that button. This is essentially the same as the RemoveButton function with the exception of deallocating the memory. Unless you are not going to adding any more buttons for the remainder of the game, it is best to use RemoveButton instead so additional memory allocation is not required.

Example:

 Verbcoin.DeallocateButton(btnTalk);

Deallocates btnTalk from the module's memory, and removes it from the verbcoin. Again, you normally would NOT want or need to use this, but if you are certain you are not going to be adding any more buttons to the verbcoin then it can release the memory that was allocated by the button.

See Also: Verbcoin.RemoveButton, Verbcoin.AllocateButtonMemory, Verbcoin.DeallocateButtonMemory

Verbcoin.DeallocateButtonMemory

void Verbcoin.DeallocateButtonMemory()

Completely deallocates all memory associated with the verbcoin's buttons. This will effectively therefore remove all buttons from the verbcoin, and will also erase any custom interaction text set by the SetActionText functions. Consider this carefully before calling this function, because even if you allocate the memory again later, all prior data will be lost.

Example:

 Verbcoin.DeallocateButtonMemory();

This would completely and totally obliterate the data the module was using to keep track of the relations between your buttons and the items in your game. Useful perhaps if you're permanently disabling the module.

See Also: Verbcoin.AllocateButtonMemory, Verbcoin.DeallocateButton

License

Permission is hereby granted, free of charge, to any person obtaining a copy of this script module and associated documentation files (the "Module"), to deal in the Module without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sublicense copies of the Module, and to permit persons to whom the Module is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Module.

No copy or substantial portion of the Module shall be sold with the exception of those copies or portions which are a compiled portion of other software. The Module shall not be sold in the form of non-compiled script.

THE MODULE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE MODULE OR THE USE OR OTHER DEALINGS IN THE MODULE.

Changelog

Version 1.1

 Version:      1.1
 Author:       monkey_05_06
 Date:         19 April 2011
 Description:  Added Verbcoin.MouseButtonToUse and Verbcoin.IgnoreInventoryClicks to make the module more customizable, revised behavior of the DoubleClicked property to something more sensible, optimized the way in which MaxButtonCount is set, and corrected documentation for IgnoreHotspot0.

Version 1.0b

 Version:      1.0b
 Author:       monkey_05_06
 Date:         03 March 2011
 Description:  Removed references to String.IsNullOrEmpty to allow full backwards-compatibility to AGS 3.0. Module is now fully compatible with AGS 3.0+. No further changes made.

Version 1.0a

 Version:      1.0a
 Author:       monkey_05_06
 Date:         13 February 2011
 Description:  Fixed a line which required AGS 3.2 to fix compatibility with prior AGS versions. No other changes made.

Version 1.0

 Version:      1.0
 Author:       monkey_05_06
 Date:         12 February 2011
 Description:  First public release.