How do associated characters work?

[fredthedeadhead]

What's the purpose of LuaPlayer.get_associated_characters()? I've run a quick test and it doesn't return anything - why isn't LuaPlayer.character included in the result (when the player is connected)?

[Bilka]

Hey, I moved this to modding help.

The reason the player.character is not included in the result is that it is controlled by the player. As the doc says, the function is for any characters that are associated with a player but "are NOT controlled by any player".

[fredthedeadhead]

The reason the player.character is not included in the result is that it is controlled by the player. As the doc says, the function is for any characters that are associated with a player but "are NOT controlled by any player".

Sorry I don't understand. The full section says

Note: Characters associated with this player will be logged off when this player disconnects but are not controlled by any player.

I read that as a description of an action (associated characters will be logged off) that will be performed upon characters that are associated with this player, under two conditions: 1. the player disconnects, and 2. the character isn't controlled by any player (I guess the implication is that a character can be controlled by multiple players?).

[quale]

That sentence is a bit dense. It’s easier to interpret when split like this:

Characters associated with this player will be logged off when this player disconnects. (an action that will occur under a specific condition)
Characters associated with this player are not controlled by any player. (an invariant)

“Characters associated with this player will be logged off when are not controlled by any player” wouldn’t work.

I don’t see how it implies multiple players can be associated. Indeed, LuaEntity’s associated_character implies only one player can be associated.

[mrvn]

You can read the note as:

Characters associated with this player will be logged off when (this player disconnects but are not controlled by any player.)

Parsing the sentence that way the any becomes a condition for logging off. That would imply there are associated characters that are controlled by some player. One misunderstanding causes another.

Might be clear to a native english speaker but it's a big world. Maybe switch the two around:

Characters associated with this player are not controlled by any player but will be logged off when this player disconnects.

Looks to me like it would be harder to misread.

[fredthedeadhead]

Thanks for the explanations - I understand the documentation better now.

Would this re-write make sense? (original)

A list of logged-in characters that are associated with this player.

Associated characters are not controlled by the player (TODO what does 'controlled ' mean?).

Characters can be associated with zero or one players. Players can be associated with zero to many characters.

Note: LuaPlayer.character is not included in this list because that character is controlled by the player, and so is not considered associated.

Note: The array will always be empty when the player is disconnected (see LuaPlayer::connected) regardless of there being associated characters.

Note: A player's associated characters will be logged off when this player disconnects.

I'm still confused by some aspects though. What does it mean for a character to be 'controlled'? What does it mean, for a character to be 'logged in'? I can't find any reference to the login status in the docs, except when it comes to associated characters. Are associated characters automatically logged in when a player reconnects?

I suspect things would become more clear if I could understand the purpose of associated characters. What are they for? Why might they exist? What process or event associates them with a character? Are they a common occurrence, or rare?

[Pi-C]

I suspect things would become more clear if I could understand the purpose of associated characters. What are they for? Why might they exist? What process or event associates them with a character? Are they a common occurrence, or rare?

Bob's classes and character mod, for example, allows you to construct characters and leave avatars of yourself in the world. Say, your current character is of the miner's class. It's your character (player.character) which you are currently controlling: You move it up with <W>, you let it mine something, or you open its inventory. Let's say you also have a fighter class avatar. It's standing around somewhere on the surface but you're not controlling it. It's just an associated character until you choose to switch to it. At this moment, your miner class avatar will become an associated character and your fighter class avatar will be player.character.

[mrvn]

Think Avatar.

[fredthedeadhead]

Bob's classes and character mod, for example, allows you to construct characters and leave avatars of yourself in the world. Say, your current character is of the miner's class. It's your character (player.character) which you are currently controlling: You move it up with <W>, you let it mine something, or you open its inventory. Let's say you also have a fighter class avatar. It's standing around somewhere on the surface but you're not controlling it. It's just an associated character until you choose to switch to it. At this moment, your miner class avatar will become an associated character and your fighter class avatar will be player.character.

Thanks very much, the example and explanation are really useful.