[Possible Bug] The controlledby property on tokens linked to characters is not overridden

According the my understanding of the API documentation, having a token linked to a character causes the "controlledby" property, when accessed on the token, to return the same thing as the "controlledby" on the character. The text from the API docs says "Note that for tokens that are linked to Characters, the controlledby field on the token is overridden by the controlledby field on the Character." I assumed that this was done through some programmagical method when "controlledby" is accessed via the get() method. However, that does not seem to be the way it actually works. Here is a very simple test for the issue: on("ready", function(){ var page = Campaign().get("playerpageid"); var tok = findObjs({_pageid: page, _type: "graphic"})[0]; log("token"); log(tok.get("controlledby")); if(tok.get("represents").length > 0) { var c = getObj("character", tok.get("represents")); log("character"); log(c.get("controlledby")); } }); If my understanding were correct, then the log should show identical controllers if I have a token linked to a character. When I run this on just such a case, it appears that the token retains the original "controlledby" value when it is accessed, ignoring the linked character. Can anyone shed light on this? Is it a bug in the behavior of linked tokens, an error in the API documentation, or a misunderstanding on my part about what is supposed to be happening?

I think the meaning is not "The value on the token is changed to be what's in the Character", but more "no matter what's in here, if it's linked it will always use the controlledby value from the Character Sheet and the token value will be ignored". I could be wrong though, but that's how I interpret this. It's somewhat unfortunate, as you have to check if it's linked, and if so, access the charactersheet's controlledby and if not the tokens, but then again, you just write yourself a small method doing that once and returning the proper value and the problem is solved. Or you do the check once and save the proper "controller" in a local variable in your script and then work with that.

I never thought that the Token's "controlledby" would be changed. I just assumed that it would be ignored in favor of the Character's "controlledby" value if it were linked to one. I understand what you're saying about the relative painlessness of implementing that functionality. I'm not opposed to doing it myself. But my assumption (given the wording of the documentation) was that the developers just included that test and lookup in the implementation of the Token's get() method. For instance, I would have expected something like Token.prototype.get = function(property) { if(property == "controlledby") { // Check to see if this token is linked to a character. // If so, return the character's "controlledby" value. // Otherwise, return the internal "controlledby" of the token. } } That way, no one would be the wiser or would have to deal with it. There may be good reasons why that approach won't work in the system, though. However, if my doing it myself were what the developers intended, then this would be a good place to reword the documentation to make that clearer.