Difference between revisions of "Standards:GMCP Client Variables"

From Mudlet
Jump to navigation Jump to search
Line 17: Line 17:
 
</syntaxhighlight>
 
</syntaxhighlight>
 
===== Client.Variables.List =====
 
===== Client.Variables.List =====
−
'''Purpose''': The client sends a list of available client variables and their attributes with <code>Client.Variables.List</code>. The server may asynchronously respond with a <code>Client.Variables.Request</code> message.
+
'''Purpose''': The client sends an array of available client variables and their attributes with <code>Client.Variables.List</code>. The server may asynchronously respond with a <code>Client.Variables.Request</code> message.
 +
======Attribute Details======
 +
{| class="wikitable “wikitable”"
 +
|-
 +
!Attribute
 +
!Description
 +
!Value
 +
!Required
 +
|-
 +
|'''''name'''''
 +
|Client variable identifier.
 +
|(text)
 +
|yes
 +
|-
 +
|'''''available'''''
 +
|Indicates if the variable is available for use. Values that require consent default to <code>false</code>.
 +
|<code>true</code> or <code>false</code>
 +
|yes
 +
|-
 +
|'''''updatable'''''
 +
|Indicates if the variable can be updated by the server.
 +
|<code>true</code> or <code>false</code>
 +
|yes
 +
|}
 
<syntaxhighlight lang="json">
 
<syntaxhighlight lang="json">
 
Client.Variables.List [
 
Client.Variables.List [
Line 42: Line 65:
 
]
 
]
 
</syntaxhighlight>
 
</syntaxhighlight>
−
====== Attribute Details ======
+
=====Client.Variables.Request=====
 +
'''Purpose''': The server requests specific client variables with <code>Client.Variables.Request</code>. The client will synchronously respond with a <code>Client.Variables.Update</code> message.
 +
 
 +
To encourage consent to collect personal information, custom messages to describe the reason for collecting the information may be included for the client to display with the <code>purpose</code> attribute.
 +
======Attribute Details======
 
{| class="wikitable “wikitable”"
 
{| class="wikitable “wikitable”"
 
|-
 
|-
Line 48: Line 75:
 
!Description
 
!Description
 
!Value
 
!Value
 +
!Required
 
|-
 
|-
−
|'''''available'''''
+
|'''''name'''''
−
|Indicates if the variable is available for use. Values that require consent default to <code>false</code>.
+
|Client variable identifier.
−
|<code>true</code> or <code>false</code>
+
|(text)
 +
|yes
 
|-
 
|-
−
|'''''updatable'''''
+
|'''''purpose'''''
−
| Indicates if the variable can be updated by the server.
+
|Reason for collecting the information.
−
|<code>true</code> or <code>false</code>
+
|(text)
 +
|no
 
|}
 
|}
−
 
+
<syntaxhighlight lang="json">
−
=====Client.Variables.Request=====
 
−
'''Purpose''': The server requests specific client variables with <code>Client.Variables.Request</code>. The client will synchronously respond with a <code>Client.Variables.Update</code> message.
 
−
 
 
−
To encourage consent to collect personal information, custom messages to describe the reason for collecting the information may be included for the client to display with the <code>purpose</code> attribute.<syntaxhighlight lang="json">
 
 
Client.Variables.Request [
 
Client.Variables.Request [
 
     {"name": "BOLD_IS_BRIGHT"},
 
     {"name": "BOLD_IS_BRIGHT"},
Line 73: Line 99:
 
]
 
]
 
</syntaxhighlight>
 
</syntaxhighlight>
−
 
 
=====Client.Variables.Update=====
 
=====Client.Variables.Update=====
 
'''Purpose''': The client sends updates for requested variables with a <code>source</code> attribute of <code>request</code>.
 
'''Purpose''': The client sends updates for requested variables with a <code>source</code> attribute of <code>request</code>.
Line 138: Line 163:
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
−
======Attribute Details======
+
======Attribute Details ======
 
{| class="wikitable “wikitable”"
 
{| class="wikitable “wikitable”"
 
|-
 
|-
−
! Attribute
+
!Attribute
−
! Description
+
!Description
 
!Value
 
!Value
 
!Required
 
!Required
 
|-
 
|-
−
| '''''available'''''
+
|'''''available'''''
 
| Indicates if the variable is available for use.
 
| Indicates if the variable is available for use.
 
|<code>true</code> or <code>false</code>
 
|<code>true</code> or <code>false</code>
 
|Yes
 
|Yes
 
|-
 
|-
−
| '''''updatable'''''
+
|'''''updatable'''''
−
| Indicates if the variable can be updated by the server.
+
|Indicates if the variable can be updated by the server.
 
|<code>true</code> or <code>false</code>
 
|<code>true</code> or <code>false</code>
 
|Yes
 
|Yes
 
|-
 
|-
−
| '''''requested'''''
+
|'''''requested'''''
−
| Indicates if the variable was requested by the server.
+
|Indicates if the variable was requested by the server.
 
|<code>true</code> or <code>false</code>
 
|<code>true</code> or <code>false</code>
 
|Yes
 
|Yes
 
|-
 
|-
−
| '''''source'''''
+
|'''''source'''''
−
| Indicates the source of the update.
+
|Indicates the source of the update.
 
|<code>request</code> or <code>client</code> or <code>server</code>
 
|<code>request</code> or <code>client</code> or <code>server</code>
−
|Yes
+
| Yes
 
|-
 
|-
−
| '''''timestamp'''''
+
|'''''timestamp'''''
−
| Unix timestamp indicating when the update was made.
+
|Unix timestamp indicating when the update was made.
 
|10-digit (or less) number
 
|10-digit (or less) number
 
|Yes
 
|Yes
Line 177: Line 202:
 
|-
 
|-
 
|'''''value'''''
 
|'''''value'''''
−
| The value of the variable.
+
|The value of the variable.
 
|
 
|
−
|When '''''available''''' is <code>true</code>and a value exists.
+
| When '''''available''''' is <code>true</code>and a value exists.
 
|}
 
|}
  
Line 213: Line 238:
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
−
===Implementation Considerations===
+
===Implementation Considerations ===
  
 
*'''Client Support Advertisement''': Clients should advertise their support for the Client.Variables namespace using Core.Supports.Set.
 
*'''Client Support Advertisement''': Clients should advertise their support for the Client.Variables namespace using Core.Supports.Set.
Line 324: Line 349:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==== Flow Diagrams ====
+
====Flow Diagrams====
  
−
====== Requesting and Receiving Variables ======
+
======Requesting and Receiving Variables======
 
[[File:Flow1.png|alt=GMCP Client Variables Flow 1|frameless|600x600px]]
 
[[File:Flow1.png|alt=GMCP Client Variables Flow 1|frameless|600x600px]]
  
−
====== Receiving Variable Updates ======
+
======Receiving Variable Updates ======
  
  
 
[[File:Flow2.png|alt=GMCP Client Variables Flow 2|frameless|600x600px]]
 
[[File:Flow2.png|alt=GMCP Client Variables Flow 2|frameless|600x600px]]
  
−
====== Setting Updatable Variables ======
+
======Setting Updatable Variables======
  
  
Line 343: Line 368:
  
 
==Versions==
 
==Versions==
−
*Version 1.0: Initial specification.
+
* Version 1.0: Initial specification.
  
 
==Authors==
 
==Authors==
 
*Mike Conley (Tamarindo, Administrator at StickMUD and Mudlet contributor) mike.conley[at]stickmud.com
 
*Mike Conley (Tamarindo, Administrator at StickMUD and Mudlet contributor) mike.conley[at]stickmud.com
  
−
===Notes===
+
===Notes ===
 
*This specification is subject to updates and community input. Contributions and feedback are welcome to ensure it meets the needs of the MUD community in the #mudlet-development channel of the Mudlet Discord.
 
*This specification is subject to updates and community input. Contributions and feedback are welcome to ensure it meets the needs of the MUD community in the #mudlet-development channel of the Mudlet Discord.
 
*Implementation should follow GMCP protocol specifications, and all messages must be well-formatted JSON objects.
 
*Implementation should follow GMCP protocol specifications, and all messages must be well-formatted JSON objects.

Revision as of 12:21, 10 August 2024

GMCP Client Variables Sharing Standard

Overview and Rationale

The GMCP Client Variables Sharing extension provides a standardized way to exchange client-specific variables between MUD clients and game servers using GMCP messages. This facilitates enhanced user experiences by allowing servers to adjust gameplay and UI elements based on client-provided data.

Rationale

As MUDs become more complex, the need for customizable and dynamic interactions between clients and servers has grown. Sharing client-specific variables allows for personalized gameplay experiences, seamless UI adjustments, and improved accessibility features. By standardizing this exchange, the GMCP Client Variables Sharing extension ensures that all participants in the MUD ecosystem can benefit from enhanced communication and data sharing.

Consent Management Process

A critical aspect of sharing client-specific variables is obtaining user consent. This process ensures that users are aware of what data is being shared and have control over their personal information. This exchange of information is geared towards finding out what data is available in the client, receiving only what is needed from the server or script, and prompting the user for fields where consent is necessary and the fields are desired.

Specification for Client.Variables

Commands

Client.Variables.Default

Purpose: Client.Variables.Default is sent by the server to acknowledge support for the Client.Variables namespace. The client will synchronously respond with a Client.Variables.List message. 

Client.Variables.Default {}
Client.Variables.List

Purpose: The client sends an array of available client variables and their attributes with Client.Variables.List. The server may asynchronously respond with a Client.Variables.Request message.

Attribute Details
Attribute Description Value Required
name Client variable identifier. (text) yes
available Indicates if the variable is available for use. Values that require consent default to false. true or false yes
updatable Indicates if the variable can be updated by the server. true or false yes 
Client.Variables.List [
    {"name": "256_COLORS", "available": true, "updatable": false},
    {"name": "ANSI", "available": true, "updatable": false},
    {"name": "BOLD_IS_BRIGHT", "available": true, "updatable": true},
    {"name": "CHARSET", "available": true, "updatable": true},
    {"name": "CLIENT_NAME", "available": true, "updatable": false},
    {"name": "CLIENT_VERSION", "available": true, "updatable": false},
    {"name": "FONT", "available": false, "updatable": false},
    {"name": "FONT_SIZE", "available": false, "updatable": false},
    {"name": "LANGUAGE", "available": false, "updatable": false},
    {"name": "MTTS", "available": true, "updatable": false},
    {"name": "OSC_COLOR_PALETTE", "available": true, "updatable": false},
    {"name": "SCREEN_READER", "available": false, "updatable": false},
    {"name": "SYSTEMTYPE", "available": false, "updatable": false},
    {"name": "TERMINAL_TYPE", "available": true, "updatable": false},
    {"name": "TLS", "available": true, "updatable": false},
    {"name": "TRUECOLOR", "available": true, "updatable": false},
    {"name": "USER", "available": false, "updatable": false},
    {"name": "UTF-8", "available": true, "updatable": false},
    {"name": "VT100", "available": true, "updatable": false},
    {"name": "WORD_WRAP", "available": true, "updatable": false}
]
Client.Variables.Request

Purpose: The server requests specific client variables with Client.Variables.Request. The client will synchronously respond with a Client.Variables.Update message.

To encourage consent to collect personal information, custom messages to describe the reason for collecting the information may be included for the client to display with the purpose attribute.

Attribute Details
Attribute Description Value Required
name Client variable identifier. (text) yes
purpose Reason for collecting the information. (text) no 
Client.Variables.Request [
    {"name": "BOLD_IS_BRIGHT"},
    {"name": "CHARSET"},
    {"name": "FONT", "purpose": "Match client font to other user interface elements"},
    {"name": "FONT_SIZE", "purpose": "Match client font size to other user interface elements"},
    {"name": "LANGUAGE", "purpose": "Match client language to adjust game and user interface content"},
    {"name": "SCREEN_READER", "purpose": "Enable accessible features to adjust game and user interface content"},
    {"name": "SYSTEMTYPE", "purpose": "Consider client operating system to adjust game and user interface elements"},
    {"name": "USER", "purpose": "Indicate client account:character name to the game server"}
]
Client.Variables.Update

Purpose: The client sends updates for requested variables with a source attribute of request. 

Client.Variables.Update {
    "BOLD_IS_BRIGHT": {
        "available": true,
        "updatable": true,
        "requested": false,
        "source": "request",
        "timestamp": 1721495879,
        "value": 2
    },
    "CHARSET": {
        "available": true,
        "updatable": true,
        "requested": false,
        "source": "request",
        "timestamp": 1721495879,
        "value": "UTF-8"
    },
    "FONT": {
        "available": false,
        "updatable": false,
        "requested": true,
        "source": "request",
        "timestamp": 1721495879
    },
    "FONT_SIZE": {
        "available": false,
        "updatable": false,
        "requested": true,
        "source": "request",
        "timestamp": 1721495879
    },
    "LANGUAGE": {
        "available": false,
        "updatable": false,
        "requested": true,
        "source": "request",
        "timestamp": 1721495879
    },
    "SCREEN_READER": {
        "available": false,
        "updatable": false,
        "requested": true,
        "source": "request",
        "timestamp": 1721495879
    },
    "SYSTEMTYPE": {
        "available": false,
        "updatable": false,
        "requested": true,
        "source": "request",
        "timestamp": 1721495879
    },
    "USER": {
        "available": false,
        "updatable": false,
        "requested": true,
        "source": "request",
        "timestamp": 1721495879
    }
}
Attribute Details
Attribute Description Value Required
available Indicates if the variable is available for use. true or false Yes
updatable Indicates if the variable can be updated by the server. true or false Yes
requested Indicates if the variable was requested by the server. true or false Yes
source Indicates the source of the update. request or client or server Yes
timestamp Unix timestamp indicating when the update was made. 10-digit (or less) number Yes
success Indicates if an updatable variable changed. true or false Only sent in response to Client.Variables.Set messages.
value The value of the variable. When available is trueand a value exists.
Client.Variables.Set

Purpose: The server sets one or more previously requested, updatable client variables. The client will synchronously respond with a Client.Variables.Update with a source attribute of server. 

// Client request with a valid and invalid value
Client.Variables.Set {
    "BOLD_IS_BRIGHT" : 1,
    "CHARSET" : "DEEP-6"
}

// Server response to a valid and invalid value
Client.Variables.Update {
    "BOLD_IS_BRIGHT": {
        "available": true,
        "updatable": true,
        "requested": true,
        "source": "request",
        "timestamp": 1721495900,
        "success": true,
        "value": 1
    },
    "CHARSET": {
        "available": true,
        "updatable": true,
        "requested": false,
        "source": "request",
        "timestamp": 1721495900,
        "success": false,
        "value": "DEEP-6"
    }
}

Implementation Considerations

  • Client Support Advertisement: Clients should advertise their support for the Client.Variables namespace using Core.Supports.Set.
  • Server Acknowledgement: Servers acknowledge support with Client.Variables.Default.
  • Consent Management: Clients must handle user consent for sharing sensitive variables. Prompts should inform users of requested data and allow them to opt-in or block requests.
  • Blocked Variables: Clients should not share a variable previously blocked by a user in Client.Variables.List messages, nor made available to other protocols, such as NEW-ENVIRON, MNES, MTTS.
  • Variable Naming Convention: Variables should be transferred in uppercase to maintain consistency and avoid issues with case sensitivity.
  • Legacy Support: Game drivers may not be able to send boolean values. Where boolean values are expected, clients will transform "true" or 1 to true, and "false" or 0 to false.

Example Flow

1. Client: Should advertise support. 

Core.Supports.Set ["Client.Variables 1", ...]

2. Server: May acknowledge support. 

Client.Variables.Default {}

3. Client: Must send available variables list. Variables previously blocked by the user should not be sent. 

Client.Variables.List {
    "256_COLORS": {"available": true, "updatable": false},
    "ANSI": {"available": true, "updatable": false},
    "BOLD_IS_BRIGHT": {"available": true, "updatable": true},
    "CHARSET": {"available": true, "updatable": true},
    "CLIENT_NAME": {"available": true, "updatable": false},
    "CLIENT_VERSION": {"available": true, "updatable": false},
    "FONT": {"available": false, "updatable": false},
    "FONT_SIZE": {"available": false, "updatable": false},
    "LANGUAGE": {"available": false, "updatable": false},
    "MTTS": {"available": true, "updatable": false},
    "OSC_COLOR_PALETTE": {"available": true, "updatable": false},
    "SCREEN_READER": {"available": false, "updatable": false},
    "SYSTEMTYPE": {"available": false, "updatable": false},
    "TERMINAL_TYPE": {"available": true, "updatable": false},
    "TLS": {"available": true, "updatable": false},
    "TRUECOLOR": {"available": true, "updatable": false},
    "USER": {"available": false, "updatable": false},
    "UTF-8": {"available": true, "updatable": false},
    "VT100": {"available": true, "updatable": false},
    "WORD_WRAP": {"available": true, "updatable": false}
}

4. Server: May requests specific variables. Once per connected session, the client may prompt the user with a request to share variables that are "available": false from the Client.Variables.List message.

Client.Variables.Request ["BOLD_IS_BRIGHT", "CHARSET", "FONT", "FONT_SIZE", "LANGUAGE", "SCREEN_READER", "SYSTEMTYPE", "USER"]

5. Client: Updates requested variables. 

Client.Variables.Update {
    "BOLD_IS_BRIGHT": {
        "available": true,
        "updatable": true,
        "requested": false,
        "source": "request",
        "timestamp": 1721495879,
        "value": 2
    },
    "CHARSET": {
        "available": true,
        "updatable": true,
        "requested": false,
        "source": "request",
        "timestamp": 1721495879,
        "value": "UTF-8"
    },
    "FONT": {
        "available": false,
        "updatable": false,
        "requested": true,
        "source": "request",
        "timestamp": 1721495879
    },
    "FONT_SIZE": {
        "available": false,
        "updatable": false,
        "requested": true,
        "source": "request",
        "timestamp": 1721495879
    },
    "LANGUAGE": {
        "available": false,
        "updatable": false,
        "requested": true,
        "source": "request",
        "timestamp": 1721495879
    },
    "SCREEN_READER": {
        "available": false,
        "updatable": false,
        "requested": true,
        "source": "request",
        "timestamp": 1721495879
    },
    "SYSTEMTYPE": {
        "available": false,
        "updatable": false,
        "requested": true,
        "source": "request",
        "timestamp": 1721495879
    },
    "USER": {
        "available": false,
        "updatable": false,
        "requested": true,
        "source": "request",
        "timestamp": 1721495879
    }
}

Flow Diagrams

Requesting and Receiving Variables

GMCP Client Variables Flow 1

Receiving Variable Updates

GMCP Client Variables Flow 2

Setting Updatable Variables

GMCP Client Variables Flow 3

Conclusion

The GMCP Client Variables Sharing extension standardizes the exchange of client-specific variables, ensuring seamless integration and enhanced user experiences. By adopting this standard, MUD developers can streamline variable management, improve client-server communication, and provide more personalized gaming experiences.

Versions

  • Version 1.0: Initial specification.

Authors

  • Mike Conley (Tamarindo, Administrator at StickMUD and Mudlet contributor) mike.conley[at]stickmud.com

Notes

  • This specification is subject to updates and community input. Contributions and feedback are welcome to ensure it meets the needs of the MUD community in the #mudlet-development channel of the Mudlet Discord.
  • Implementation should follow GMCP protocol specifications, and all messages must be well-formatted JSON objects.
Retrieved from "https://wiki.mudlet.org/index.php?title=Standards:GMCP_Client_Variables&oldid=21991"