/
MessagingService.yaml
196 lines (183 loc) · 4.83 KB
/
MessagingService.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
name: MessagingService
type: class
category:
memory_category: Instances
summary: |
Allows servers of the same experience to communicate with each other.
description: |
**MessagingService** allows servers of the same experience to communicate with
each other in real time (less than 1 second) using topics. Topics are
developer‑defined strings (1–80 characters) that servers use to send and
receive messages.
Delivery is best effort and not guaranteed. Make sure to architect your
experience so delivery failures are not critical.
[Cross-Server Messaging](../../../cloud-services/cross-server-messaging.md)
explores how to communicate between servers in greater detail.
If you want to publish ad-hoc messages to live game servers, you can use the
[Open Cloud APIs](../../../cloud/open-cloud/usage-messaging.md).
#### Limitations
Note that these limits are subject to change.
<table>
<thead>
<tr>
<th>Limit</th>
<th>Maximum</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<b>Size of message</b>
</td>
<td>
1kB
</td>
</tr>
<tr>
<td>
<b>Messages sent per game server</b>
</td>
<td>
600 + 240 * (number of players in this game server) per minute
</td>
</tr>
<tr>
<td>
<b>Messages received per topic</b>
</td>
<td>
(40 + 80 * number of servers) per minute
</td>
</tr>
<tr>
<td>
<b>Messages received for entire game</b>
</td>
<td>
(400 + 200 * number of servers) per minute
</td>
</tr>
<tr>
<td>
<b>Subscriptions allowed per game server</b>
</td>
<td>
20 + 8 * (number of players in this game server)
</td>
</tr>
<tr>
<td>
<b>Subscribe requests per game server</b>
</td>
<td>
240 requests per minute
</td>
</tr>
</tbody>
</table>
code_samples:
inherits:
- Instance
tags:
- NotCreatable
- Service
- NotReplicated
deprecation_message: ''
properties: []
methods:
- name: MessagingService:PublishAsync
summary: |
Invokes the supplied callback whenever a message is pushed to the topic.
description: |
This function sends the provided message to all subscribers to the topic,
triggering their registered callbacks to be invoked.
Yields until the message is received by the backend.
code_samples:
parameters:
- name: topic
type: string
default:
summary: |
Determines where the message is sent.
- name: message
type: Variant
default:
summary: |
The data to include in the message.
returns:
- type: void
summary: ''
tags:
- Yields
deprecation_message: ''
security: None
thread_safety: Unsafe
- name: MessagingService:SubscribeAsync
summary: |
Begins listening to the given topic.
description: |
This function registers a callback to begin listening to the given topic.
The callback is invoked when a topic receives a message. It can be called
multiple times for the same topic.
#### Callback
The callback is invoked with a single argument, a table with the following
entries:
<table>
<thead>
<tr>
<th>Field</th>
<th>Summary</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<b>Data</b>
</td>
<td>
Developer supplied payload
</td>
</tr>
<tr>
<td>
<b>Sent</b>
</td>
<td>
Unix time in seconds at which the message was sent
</td>
</tr>
</tbody>
</table>
It yields until the subscription is properly registered and returns a
connection object.
To unsubscribe, call `Datatype.RBXScriptConnection|Disconnect()` on the
returned object. Once called, the callback should never be invoked.
Killing the script containing the connections also causes the underlying
connect to be unsubscribed.
See also `Class.MessagingService:PublishAsync()` which sends the provided
message to all subscribers to the topic, triggering their registered
callbacks to be invoked.
code_samples:
- subscribing-to-cross-server-messages
parameters:
- name: topic
type: string
default:
summary: |
Determines where to listen for messages.
- name: callback
type: Function
default:
summary: |
Function to be invoked whenever a message is received.
returns:
- type: RBXScriptConnection
summary: |
Connection that can be used to unsubscribe from the topic.
tags:
- Yields
deprecation_message: ''
security: None
thread_safety: Unsafe
events: []
callbacks: []