Extensions: Programming Interface

A list maintained by Omnidon to provide a recap of all user-submitted feature requests for BRPG.

Is this summary thorough?

Yes
3
75%
No (Please Explain)
0
No votes
Don't Know
1
25%
 
Total votes: 4

User avatar
Omnidon
Site Admin
Posts: 2186
Joined: Mon Feb 06, 2006 7:46 pm
Location: NY State, USA
Contact:

Extensions: Programming Interface

Post by Omnidon » Sat Aug 04, 2007 4:51 am

Relevant to BRPG version: 1.3

This summary is intended for advanced users only. For a basic understanding of Flash and how it can improve BRPG, refer to my summary of Flash Integration.

The following article details the technical principles of Flash-Lingo communication:
http://director-online.com/buildArticle.php?id=468
  • API = Application Programming Interface
    An API is the set of functions and variables used to allow communication between two or more distinct applications.

    Many of the features I discuss here are likely already possible without any additional framework in place, but merely require knowledge of the functions and variables BRPG already uses. Also, some features, such as the ability for a flash application to detect its current size, can probably already be done just with ActionScript.

    When I speak of the "properties" of a unit, I mean *all* properties.
    (Owner, Location, Unit type, Hidden, Locked, Tile, Light source, Registration point. etc.)
    Changes to a unit's position would be teleport-style unless a move-order is specifically given.

    A true 'extension' is an application that integrates with the interface itself. To get the most out of these features, we would need the ability to add interface elements that are preserved between sessions and that are not linked to a specific encounter. This list is written with the assumption that maps, grids, figures, objects, visual aids, portraits, etc all support the SWF filetype.

    Some features mentioned may have usability concerns. These features should still be added, but it might be good to eventually add the option to disable them in the preferences. Of course, flash applications should be able to retrieve a list of disabled features.

    When I use the word "Detect", I mean that it must be possible for a flash application to instruct BRPG to send a message every time the given event occurs.

    The list of features below may not be complete and does account for certain planned features such as tabbed encounters or the dynamic turn sequencer.
  • Highest Priority

    Every flash application must be able to:
    • Retrieve its own name and properties.
    • Detect changes to its own properties (including movement).
    • Detect its own turn.
    • Retrieve a list of connected users.
    • Retrieve the name of the local machine's user.
    • Send variables to itself on the machines of remote users.
    • Save variables in the encounter file when the encounter is saved.
    • Disable transparency and other attributes automatically applied to imported Flash media by BRPG.
  • High Priority

    Every flash application should be able to:
    • Retrieve the turn sequencer order.
    • Retrieve whose turn it is.
    • Detect turn stepping.
    • Retrieve the properties of the current map.
    • Retrieve the properties of the current grid.
    • Retrieve a list of figures, objects, visual aids, etc.
    • Retrieve the properties of any of the above.
    • Send variables to itself on the machines of remote users selectively.
    • Send variables to other flash applications on the local machine.
    • Send variables to other flash applications on the machines of remote users selectively.
    • Change its own properties.
    • Move (animated) itself.
    • Read data from files.
    • Detect cursor mode. (Drawing, normal, etc.)
    • Disable context menu.
    • Disable right-click scrolling.
    • Disable hotkeys (including number movement keys, arrow keys, etc).
    • Disable scrollwheel zoom.
    • Add files to a bundle when the Export feature is used.
    • Access files in User Cast by calling filename.
  • Medium Priority

    Every flash application should be able to:
    • Detect map changes.
    • Retrieve map settings.
    • Retrieve FoW settings.
    • Retrieve grid settings.
    • Retrieve encounter name.
    • Retrieve preferences.
    • Detect changes to map settings.
    • Detect changes to FoW settings.
    • Detect changes to grid settings.
    • Change the map.
    • Change map settings.
    • Change FoW settings.
    • Purge media / trigger file refresh by filename.
    • Change the properties of other figures, objects, visual aids, etc.
    • Move (animated) other units.
    • Place new units. ***
    • Delete units.
    • Retrieve a user's license information. ***
    • Save the encounter.
    • Load an encounter.
    • Send variables to a new/loaded encounter or save variables in a session cache.
    • Write data to files.
    • Listen for changes to a file.
    • Change the current user's field of view / Force center on point.
    • Launch file in default viewer.
  • Low Priority

    It would be nice if every flash application could:
    • Change the grid.
    • Change grid settings.
    • Detect dice rolls.
    • Send dice rolls.
    • Retrieve the chat log.
    • Detect chat messages.
    • Send chat messages.
    • Add itself to the chat list so users can whisper to it.
    • Detect when a unit move is in progress. (So it can, for example, add a walking animation)
    • Detect when a unit drag is in progress. (So it can, for example, change to a drag & drop icon)
    • Detect unit overlaps.
    • Detect drawing overlaps with units.
    • Open a panel.
    • Add a new panel.
    • Detect local user's current field of view (changes on scroll).
    • Remove items from the context menu.
    • Remove items from the B-menu.
    • Add items to the context menu.
    • Add items to the B-menu.
    • Detect events triggered by such custom menu items.
    • Hide the B-menu.
    • Automatically be loaded as the default handler for objects, figures, and/or map images.
    *** The "Place new unit" function would allow an extension to get around the demo limitations, and thus should be disabled when running in demo mode.

    *** By "Retrieve a user's license information", I mean it should be possible for the flash application to determine who has a *valid* GM license, who has a *valid* player license, who is using a floating license, and who will timeout in 45 minutes.
    Additionally, while the licensing scheme is still linked solely to the user's hard drive, there is no reason why the flash application should not be able to detect the actual license code. This would allow flash developers to use the BRPG license system to ensure licensed usage of their own products.
  • Example Functions
    I was originally planning to create a list of sample functions, but figured heruca would know the easiest way to do things.
    I can still make some examples or explain the purpose of a feature if needed. Just ask.
  • Related Links

    Flash-Lingo Integration Basics
    http://director-online.com/buildArticle.php?id=468

    Flash 8 Xtra Official Documentation
    http://www.adobe.com/support/director/f ... t_xtra.pdf

    Passing Variables to Lingo using Flash
    http://director-online.com/buildArticle.php?id=949
    &
    http://kb.adobe.com/selfservice/viewCon ... &sliceId=1

    Setting and calling Flash variables using Lingo
    http://livedocs.adobe.com/director/mx20 ... mmon/html/...

    Accessing Flash internal functions using Lingo
    http://director-online.com/buildArticle.php?id=1044

    Sending Events to Lingo using Flash -- setCallback()
    http://livedocs.adobe.com/director/mx20 ... _me392.htm

    Adapting Flash for Use in Director
    http://www.adobe.com/devnet/director/ar ... tor_3.html
Last edited by Omnidon on Tue Nov 20, 2012 3:06 am, edited 1 time in total.

User avatar
heruca
Developer
Posts: 9370
Joined: Sun Nov 20, 2005 11:58 pm
Location: Buenos Aires, Argentina
Contact:

Post by heruca » Mon Nov 19, 2012 4:54 pm

BRPG v1.8a will support everything listed in the "Highest Priority" section, and several items from each of the other sections.

Omnidon, you might want to update the list to not mention masked/revealed FoW cells; that's really old/obsolete info.
:arrow: Please help spread the word about BRPG and BGE, and never hesitate to tell me how I can make them better suit your gaming needs.

User avatar
Omnidon
Site Admin
Posts: 2186
Joined: Mon Feb 06, 2006 7:46 pm
Location: NY State, USA
Contact:

Post by Omnidon » Tue Nov 20, 2012 3:15 am

heruca wrote:BRPG v1.8a will support everything listed in the "Highest Priority" section, and several items from each of the other sections.
Fantastic ;-)
heruca wrote:Omnidon, you might want to update the list to not mention masked/revealed FoW cells; that's really old/obsolete info.
Done.

Post Reply