+ Reply to Thread
Results 1 to 14 of 14

Thread: A Read-through of the documented API...

  1. #1
    Telaran
    Join Date
    Feb 2011
    Posts
    63

    Default A Read-through of the documented API...

    I've been reading the current docs for the current alpha API. I know--at least, I hope--that the API will expend drastically by the 22nd. I also assume the documentation is not complete, mostly because I've never seen documentation for a non-trivial API that was. I'm also ignoring little warts in the API, like redundant data, strange or confusing layout, inconsistencies, and so on; those don't actually matter much in the long term and they distract from actual analysis.

    I'm not a very experienced Lua programmer, but I have used it and I have 20+ years programming experience with a lot of it focused on developing both public and private APIs. I love addons for games (and I recognize the good points the anti-addon crowd makes, since there are jerks everywhere and many of them will abuse addons), so I'm excited by this and I really hope it works out as a net positive. Since LOTRO didn't support addons natively, I wrote an on-screen keyboard emulator to help people use LOTRO's innovative music system and eventually expanded that to arbitrary macros, like a macroing keyboard for people who don't want to buy one; I'd much rather use an official API! I want to see the API expand and grow richer, rather than dwindle to the LOTRO or City levels.

    The first pass at the published API looks like a great start, dipping the toes in the water with just one small set of character functionality (buffs) and some very simple UI. It's a good approach and a great start conversing with t he community about it.

    And I really hope that's what it is: a great start with a subset of the 1.3 functionality to get us all talking about the pros and cons and get us familiar with the (pretty much WoW-influenced) design.

    To that end, I put together a Can/Unknown/Can't list to help me understand what kinds of addons I can make and can't. Thought I'd share it.

    I also have a re-format of the API doc, much shorter, grouped by when and how I think someone (such as me) would use it. Posting that as well.

    And another disclaimer: I'm almost certainly wrong about a bunch of stuff here. I'd love to know what. Feedback is good. *Polite* feedback is better, but I know better than to expect that :-)

    ================================================== ===========================
    Can:
    Perform basic dev and compsci tasks (gc, error/assert, math, bit twiddling)
    - Including helpful methods for coroutines
    Use some handy helpers for strings and tables
    Get some interesting system information (time, cpu info, Rift version)
    Handle basic addon life cycle events
    Create slash commands that run Lua code (but not persistent?)
    Handle buffs: Enumerate a unit's buffs, get information on a buff (including caster, time remaining, and stack count), and cancel a buff on the current player
    Create UI frames, position them, show/hide/alpha them, set background color, and create child frames
    Create text frames: Set text, fonts, and text color. Use wordrap. Resize to fit.
    Create texture frames from files or well-known textures

    ================================================== ===========================
    Unknown:
    Can we call a slash command event as if the user typed it?
    - If so, what are the arguments? Can we pass tokens?
    - If so, can the return be obtained? Can it be shown in the chat frame? Can it be prevented from showing in the chat frame?
    What are the options for sending text to the chat log? To the player's rw/info frame?
    Can the chat log function(s) send messages to another player? To party or raid? To general channels?
    Can we run addons at character selection (to show more information about a character, for example)?
    Do combo points show in the debuffs list on a target?

    ================================================== ===========================
    Can't:
    Tell anything about the user other than buffs:
    Name, gender, race
    Location, heading (unless /loc can be parsed)
    Equipment worn, Wardrobe shown
    Change equipment (unless slash commands can be run)
    Changed wardrobe (no current slash command for this)
    Obtain current setting values, such as head armor display, action bar display, particle count, or grouping options
    Change settings, such as showing head armor, displaying action bars, setting particle count, or setting grouping options
    Examine bags or bank to identify what is available
    Examine, edit, create, delete or execute macros
    Determine if the character is in combat
    Track chat log
    Track combat log
    Edit the UI layout
    Play sounds
    Add display to the minimap or full map, except possibly with kludges
    Communicate with addons running on other players (FlagRSP, guild information sharing)
    Inspect tradeskills or recipes; execute tradeskills
    Use an ability (unless /cast can be executed)
    Determine target or focus
    Identify party or raid members
    Get character's health, secondary attribute, or tertiary attribute (health, energy, warrior sword thingies)
    Get character's soul-specific attributes
    Inspect the character's souls, talents, and abilities
    Identify the character's titles or current title; change the character's current title
    Inspect the character's currency
    Inspect the character's notoriety
    Identify a character's guild and guild rank
    Identify the character's guild, guild rank, current guild quest, current guild member's online, and guild roster
    Perform any guild activies (that can't be performed from the command line, if slash commands work)
    Enumerate the character's guild perks
    Enumerate the quest log
    Abandon quests, select quests for tracking, select currently hot quest for tracking
    Interacting with the queuing system, to change selected roles, alert when a queue pops, and so forth
    Determine if the user is AFK or DND or react when those states change
    Cause the character to move or select a porticuluum location (may be able to use recall or a rally scroll, though)

    Identify when another frame opens (such as a merchant dialog)
    Select items in another frame (such as purchasing from a merchant or selling items, unless those can be done with a /use command)
    Disable default UI frames (to show a custom bank, for example)
    Add to the default UI (to add a tab or button to the character screen, for example)

  2. #2
    Telaran
    Join Date
    Feb 2011
    Posts
    63

    Default Drouped API list

    This is intended to organize *documented* API elements by use cases, rather
    than objects and the alphabet used in Lua. It's just a start on understanding
    the API capabilities and intention.

    These are not always exact methods names. Mostly, I've inserted spaces in
    some places. Use the real docs for exact spellings and details on arguments
    and types.

    I've formatted for 78 characters wide, for those of you who need to read
    this after it's forwarded with the standard "> " line prepender to your
    VT-52 terminal. It is also possible that I'm a bit of an old fuddy duddy
    who should consider some new habits.

    ================================================== ===========================

    Development Basics:
    Methods: assert, collectgarbage, debug.traceback, error, gcinfo
    Events: Event.System.Error, Event.System.Update.Begin,
    Event.System.Update.End

    Data object helpers:
    String: byte, char, find, format, gfind, gmatch, gsub, len, lower,
    match, rep, reverse, sub, upper
    Table: concat, foreach, foreachi, getn, insert, maxn, remove, sort

    ================================================== ===========================
    System Info:
    Inspect.System.Time() time: Time in seconds
    Global constant: _VERSION

    ================================================== ===========================
    Addon Information:
    Inspect.Addon.Cpu() Recent CPU usage
    Inspect.Addon.Current() The addon's identifier from its TOC file
    Addon Events:
    Event.Addon: Finalizing, Load.Begin, Load.End
    SavedVariables.Load.Begin, SavedVariables.Load.End
    SavedVariables.Save.Begin, SavedVariables.Save.End
    Shutdown, Starting

    ================================================== ===========================
    Slash commands:
    Command.Slash.Register(name) The event table for your slash command
    Event.Slash Empty category for dynamically-created events

    ================================================== ===========================
    Unit affecting:
    Inspect.Buff.Detail(unit, buff) Detail table for a single buff
    Inspect.Buff.Detail(unit, buffsTable) The unit's buffs' detail tables
    Inspect.Buff.List(unit) List of IDs of buffs on the unit
    Command.Buff.Cancel(buff) Cancels a buff on the player

    ================================================== ===========================
    UI:
    CreateContext(name)
    CreateFrame(type, name, parent) Type can be ["Text"|"Frame"|"Texture"]
    Layout:
    RO Owner, Name,
    Top, Left, Right, Bottom, Height, Width, Bounds
    Event Table
    Events: Move, Size
    Frame: Layout
    RW: alpha, layer, bg color, parent, visibility
    RO: location, size
    Events: LMouse down, LMouse up
    Context: Frame
    Text: Frame
    RW: Font, Font Color, Font Size, Text, Wordwrap
    Calculated: Full Height, Full Width
    Method Resize to text
    Texture: Frame
    RW: Texture
    Calculated: Texture height, Texture width
    Method: Resize to texture

    ================================================== ===========================
    CompSci stuff
    Bit twiddling: bit.arshift, bit.band, bit.bnot, bit.bor
    bit.bswap, bit.bxor
    bit.lshift, bit.rol, bit.ror, bit.rshift
    bit.tobit, bit.tohex
    Coroutines: coroutine.create, coroutine.resume, coroutine.running
    coroutine.status, coroutine.wrap, coroutine.yield
    Math: abs, acos, asin, atan, atan2, ceil, cos, cosh, deg, exp
    floor, fmod, frexp, huge, ldexp, log, log10, max, min
    mod, modf, pi, pow, rad, random, randomseed, sin, sinh
    sqrt, tan, tanh


    ================================================== ===========================
    I don't know yet:
    getmetatable, setmetatable
    next, pairs, ipairs
    load, loadstring
    rawequal, rawget, rawset
    tonumber, tostring
    type
    unpack

    I don't know yet, but looks interesting
    getfenv, setfenv
    newproxy
    pcall, xpcall
    print, print_console
    select

  3. #3
    Shadowlander
    Join Date
    Feb 2011
    Posts
    29

    Default

    Most of your don't knows are part of the LUA std lib and documented here:

    http://www.lua.org/manual/5.1/

  4. #4
    RIFT Fan Site Operator Cairenn's Avatar
    Join Date
    Jun 2011
    Posts
    154

    Default

    As well, check out Programming in Lua, a book written by the authors of the Lua programming language. The first edition is available free online at http://www.lua.org/pil and covers Lua 5.0. The second edition is available in print from most online bookstores, and covers Lua 5.1.
    "My friends, love is better than anger. Hope is better than fear. Optimism is better than despair. So let us
    be loving, hopeful and optimistic. And well change the world."
    Cairenn, Co-Founder
    and Administrator, RiftUI

  5. #5
    Rift Disciple
    Join Date
    Feb 2011
    Posts
    132

    Default

    Given how drastic addons can change the game, I'm glad they're being conservative with the APIs they are exposing. This is the first cut so I'm quite certain it is intentionally restricted so people can get a feel for how to make an addon, basic usage of the API, UI, etc. I do not think they are intending for us to go wild with addons right out of the gate, but we'll see gradual expansion over time.
    "The only constant in all your failed warfronts is you."
    Malorn, Cleric of The Enclave

  6. #6
    Ascendant Naronas's Avatar
    Join Date
    Mar 2011
    Posts
    2,699

    Default

    It's been said several times. The API is NOT even close to finished right now. Think of this as the pre-release beta test.
    Quote Originally Posted by Walsingham View Post
    Yes, if you need to know, Vespera hit me with a big pointy spiky thing. It was immensely painful.

  7. #7
    Rift Disciple blueberry's Avatar
    Join Date
    Jan 2011
    Location
    Las Vegas
    Posts
    115

    Default

    Previously I know you can use SendChatText() to send text to a specific channel. However I couldn't find this on the lua document page so is this not a lua command but an API?
    You can stalk me here

  8. #8
    Rift Disciple
    Join Date
    Feb 2011
    Posts
    163

    Default

    Quote Originally Posted by blueberry View Post
    Previously I know you can use SendChatText() to send text to a specific channel. However I couldn't find this on the lua document page so is this not a lua command but an API?
    Gah! Hidden functions! So much for self-documenting. Though given that lua is sort of global-friendly, there's probably a ton of them in there. (Oh, yes that's not lua - lua itself has barely anything but the bare essentials of a language in it.)

  9. #9
    Rift Disciple blueberry's Avatar
    Join Date
    Jan 2011
    Location
    Las Vegas
    Posts
    115

    Default

    Quote Originally Posted by ultrviolet View Post
    Gah! Hidden functions! So much for self-documenting. Though given that lua is sort of global-friendly, there's probably a ton of them in there. (Oh, yes that's not lua - lua itself has barely anything but the bare essentials of a language in it.)
    No, I wasn't being clear. I meant in other games you can use SendChatText(). So far the Rift APIs only have 2 print commands print() and print_console(). There isn't a command to send chat text to a specific chat channel yet.
    You can stalk me here

  10. #10
    Telaran
    Join Date
    Feb 2011
    Posts
    53

    Default

    Quote Originally Posted by blueberry View Post
    Previously I know you can use SendChatText() to send text to a specific channel. However I couldn't find this on the lua document page so is this not a lua command but an API?
    No, a SendChatText() function would indeed be part of an API. The Lua language is meant to be as general as possible on release, in which you can edit it to your desires, so it logically wouldn't include such a function.
    Rogue - Defiant
    Neglected - Whitefall PvP

    I stalk the AddOn section.
    Follow me on twitter for miscellaneous ramblings from within Rift.

  11. #11
    Telaran
    Join Date
    Feb 2011
    Posts
    63

    Default

    I understand that this is an extremely early API. In fact, it looks like one small-but-ready-to-alpha-test piece of an extremely early API.

    I want to check if I'm reading the current functionality: we can enumerate buffs on known units, get properties on buffs of known units, dismiss dismissable buffs on the current user, and draw frames with textures, text, alpha, fonts, and colors.

    In addition, we can register slash commands that do the above and we can respond to some interesting events around login, redraw, and addon lifespan.

    Am I reading the currently-published API correctly?

    Is this what we should expect for the 1.3 functionality?

  12. #12
    Telaran phoenik's Avatar
    Join Date
    Jan 2011
    Location
    Under your bed
    Posts
    83

    Default

    Quote Originally Posted by Xowl View Post
    Is this what we should expect for the 1.3 functionality?
    The Addon API will not be released with 1.3

  13. #13
    Telaran
    Join Date
    Feb 2011
    Posts
    63

    Default

    So 1.3 doesn't even get this. Ok.

    Some future release will contain whatever this API evolves into. That release may or may not contain a more featureful API. Ok. Nice to know.

    Product managers see to be in the (highly necessary) "see which way the wind blows" stage and aren't saying anything about what may or may not be in the API at what date. I understand. In their place, I'd do similar.

    If I spend any pre-release time with the API, it will be to look at the functionality. The current release is good for determining how people respond to the language (Lua is well-enough received) and the general design (people seem fine with the object model, the slash command implementation is fine, the event choices seem passable, and users would unsurprisingly prefer a layout-description-language for frames). Nothing else to see. Move along.

    The docs reference some items that don't seem to be extensions of the usual Lua implementations. Oddly confusing, but not really bad. Developer documentation is not expected to be perfect. That is even more true with a pre-release API.

    Thank you. My general questions seem answered: the current API lets you play with buffs and mess with some infrastructure as a "technology preview." We'll get something about functionality for addon authors later.

  14. #14
    Champion Lorandii's Avatar
    Join Date
    Jun 2011
    Posts
    516

    Default

    Correct. Trion is taking the high road and giving us content and fixes. They believe (rightfully) their API needs work, however good a start it is. Therefore addon support is not in 1.3 because that potentially would make disappointed end users -- "OK, we have addons, but all they can do is play with buffs? WTF, Trion!"

    It is much better for them to continue plugging away on the PTS, updating the APIs as necessary, than to deliver something that is not even half-assed, more like 1/000.

    The PTS will be down this week, if I have the dates correct, but Trion has said they will bring it up as soon as possible for addon authors to continue working, and to give feedback. And patch 1.4, of course.

+ Reply to Thread

Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts