0
# Audience System
1

2
Universal messaging system for sending text, media, and interactive content to players, consoles, and groups of recipients. The audience system provides a unified interface for all forms of communication in Minecraft servers.
3

4
## Capabilities
5

6
### Audience Interface
7

8
The core interface for any recipient of Minecraft media, providing methods for sending messages, displaying titles, managing boss bars, playing sounds, and more.
9

10
```java { .api }
11
/**
12
 * Universal interface for any receiver of Minecraft media
13
 */
14
interface Audience extends Pointered {
15
    // Message sending
16
    /**
17
     * Sends a chat message to this audience
18
     * @param message the message to send
19
     */
20
    void sendMessage(ComponentLike message);
21
    
22
    /**
23
     * Sends a message with a specific message type
24
     * @param message the message
25
     * @param type the message type
26
     * @deprecated for removal since 4.12.0, MessageType is deprecated for removal, use {@link #sendMessage(ComponentLike)} instead
27
     */
28
    @Deprecated
29
    void sendMessage(ComponentLike message, MessageType type);
30
    
31
    /**
32
     * Sends a signed message
33
     * @param signedMessage the signed message
34
     * @param boundChatType the chat type
35
     */
36
    void sendMessage(SignedMessage signedMessage, ChatType.Bound boundChatType);
37
    
38
    /**
39
     * Deletes a signed message
40
     * @param signature the message signature to delete
41
     */
42
    void deleteMessage(SignedMessage.Signature signature);
43
    
44
    /**
45
     * Sends an action bar message
46
     * @param message the action bar message
47
     */
48
    void sendActionBar(ComponentLike message);
49
    
50
    // Player list (tab list) management
51
    /**
52
     * Sends player list header and footer
53
     * @param header the header component
54
     * @param footer the footer component
55
     */
56
    void sendPlayerListHeaderAndFooter(ComponentLike header, ComponentLike footer);
57
    
58
    /**
59
     * Sends player list header
60
     * @param header the header component
61
     */
62
    void sendPlayerListHeader(ComponentLike header);
63
    
64
    /**
65
     * Sends player list footer
66
     * @param footer the footer component
67
     */
68
    void sendPlayerListFooter(ComponentLike footer);
69
    
70
    // Title display
71
    /**
72
     * Shows a title to this audience
73
     * @param title the title to show
74
     */
75
    void showTitle(Title title);
76
    
77
    /**
78
     * Clears the currently displayed title
79
     */
80
    void clearTitle();
81
    
82
    /**
83
     * Resets the title (clears and resets timing)
84
     */
85
    void resetTitle();
86
    
87
    /**
88
     * Sends a specific title part
89
     * @param part the title part to send
90
     * @param value the value for the title part
91
     */
92
    <T> void sendTitlePart(TitlePart<T> part, T value);
93
    
94
    // Boss bar management
95
    /**
96
     * Shows a boss bar to this audience
97
     * @param bar the boss bar to show
98
     */
99
    void showBossBar(BossBar bar);
100
    
101
    /**
102
     * Hides a boss bar from this audience
103
     * @param bar the boss bar to hide
104
     */
105
    void hideBossBar(BossBar bar);
106
    
107
    // Sound playback
108
    /**
109
     * Plays a sound to this audience
110
     * @param sound the sound to play
111
     */
112
    void playSound(Sound sound);
113
    
114
    /**
115
     * Plays a sound at a specific location
116
     * @param sound the sound to play
117
     * @param x the x coordinate
118
     * @param y the y coordinate  
119
     * @param z the z coordinate
120
     */
121
    void playSound(Sound sound, double x, double y, double z);
122
    
123
    /**
124
     * Plays a sound following an emitter
125
     * @param sound the sound to play
126
     * @param emitter the sound emitter
127
     */
128
    void playSound(Sound sound, Sound.Emitter emitter);
129
    
130
    /**
131
     * Stops sound playback
132
     * @param stop the sound stop request
133
     */
134
    void stopSound(SoundStop stop);
135
    
136
    // Books and UI
137
    /**
138
     * Opens a book for this audience
139
     * @param book the book to open
140
     */
141
    void openBook(Book book);
142
    
143
    // Resource pack management
144
    /**
145
     * Sends resource pack requests to this audience
146
     * @param request the resource pack request
147
     */
148
    void sendResourcePacks(ResourcePackRequest request);
149
    
150
    /**
151
     * Removes resource packs from this audience
152
     * @param request the resource pack removal request
153
     */
154
    void removeResourcePacks(ResourcePackRequest request);
155
    
156
    /**
157
     * Removes resource packs by info
158
     * @param first the first resource pack to remove
159
     * @param others additional resource packs to remove
160
     */
161
    void removeResourcePacks(ResourcePackInfoLike first, ResourcePackInfoLike... others);
162
    
163
    /**
164
     * Removes resource packs by UUID
165
     * @param id the first resource pack ID to remove
166
     * @param others additional resource pack IDs to remove
167
     */
168
    void removeResourcePacks(UUID id, UUID... others);
169
    
170
    /**
171
     * Removes resource packs by UUID collection
172
     * @param ids the resource pack IDs to remove
173
     */
174
    void removeResourcePacks(Iterable<UUID> ids);
175
    
176
    /**
177
     * Sends resource pack info directly
178
     * @param first the first resource pack to send
179
     * @param others additional resource packs to send
180
     */
181
    void sendResourcePacks(ResourcePackInfoLike first, ResourcePackInfoLike... others);
182
    
183
    // Audience filtering and properties
184
    /**
185
     * Filters this audience based on a predicate
186
     * @param filter the filter predicate
187
     * @return filtered audience
188
     */
189
    default Audience filterAudience(Predicate<? super Audience> filter) {
190
        return filter.test(this) ? this : Audience.empty();
191
    }
192
    
193
    /**
194
     * Executes an action against all audiences
195
     * @param action the action to perform
196
     */
197
    default void forEachAudience(Consumer<? super Audience> action) {
198
        action.accept(this);
199
    }
200
    
201
    /**
202
     * Shows a dialog to this audience (since 4.22.0, Minecraft 1.21.6)
203
     * @param dialog the dialog to show
204
     */
205
    void showDialog(DialogLike dialog);
206
    
207
    /**
208
     * Deletes a signed message
209
     * @param signedMessage the signed message to delete
210
     */
211
    void deleteMessage(SignedMessage signedMessage);
212
    
213
    /**
214
     * Stops a specific sound
215
     * @param sound the sound to stop
216
     */
217
    void stopSound(Sound sound);
218
    
219
    /**
220
     * Opens a book using a book builder
221
     * @param book the book builder
222
     */
223
    void openBook(Book.Builder book);
224
    
225
    // Factory methods
226
    /**
227
     * Creates an empty audience that ignores all operations
228
     * @return empty audience
229
     */
230
    static Audience empty();
231
    
232
    /**
233
     * Creates an audience that forwards to many other audiences
234
     * @param audiences array of audiences
235
     * @return forwarding audience
236
     */
237
    static Audience audience(Audience... audiences);
238
    
239
    /**
240
     * Creates an audience that forwards to many other audiences
241
     * @param audiences iterable of audiences
242
     * @return forwarding audience
243
     */
244
    static ForwardingAudience audience(Iterable<? extends Audience> audiences);
245
    
246
    /**
247
     * Provides a collector to create a forwarding audience from a stream
248
     * @return collector for audiences
249
     */
250
    static Collector<? super Audience, ?, ForwardingAudience> toAudience();
251
}
252
```
253

254
**Usage Examples:**
255

256
```java
257
import net.kyori.adventure.audience.Audience;
258
import net.kyori.adventure.text.Component;
259
import net.kyori.adventure.text.format.NamedTextColor;
260

261
// Send a simple message
262
audience.sendMessage(Component.text("Hello World!", NamedTextColor.GREEN));
263

264
// Send an action bar message
265
audience.sendActionBar(Component.text("Health: 100%", NamedTextColor.RED));
266

267
// Show a title
268
Title title = Title.title(
269
    Component.text("Welcome!", NamedTextColor.GOLD),
270
    Component.text("Enjoy your stay", NamedTextColor.YELLOW),
271
    Title.Times.times(Duration.ofSeconds(1), Duration.ofSeconds(3), Duration.ofSeconds(1))
272
);
273
audience.showTitle(title);
274

275
// Play a sound
276
Sound sound = Sound.sound(Key.key("entity.experience_orb.pickup"), Sound.Source.PLAYER, 1.0f, 1.0f);
277
audience.playSound(sound);
278
```
279

280
### Forwarding Audience
281

282
An audience implementation that forwards all operations to one or more underlying audiences, enabling broadcast functionality.
283

284
```java { .api }
285
/**
286
 * Audience that forwards operations to multiple underlying audiences
287
 */
288
interface ForwardingAudience extends Audience {
289
    /**
290
     * Gets the audiences that this audience forwards to
291
     * @return iterable of audiences
292
     */
293
    Iterable<? extends Audience> audiences();
294
    
295
    /**
296
     * Performs an action on each audience
297
     * @param action the action to perform
298
     */
299
    default void forEachAudience(Consumer<? super Audience> action) {
300
        for (final Audience audience : this.audiences()) {
301
            action.accept(audience);
302
        }
303
    }
304
}
305
```
306

307
### ForwardingAudience.Single Interface
308

309
Specialized forwarding audience for single target audiences.
310

311
```java { .api }
312
/**
313
 * Forwarding audience that targets a single underlying audience
314
 */
315
interface ForwardingAudience.Single extends ForwardingAudience {
316
    /**
317
     * Gets the single audience this forwards to
318
     * @return the target audience
319
     */
320
    @NotNull Audience audience();
321
    
322
    /**
323
     * Default implementation returns singleton iterable
324
     * @return iterable containing single audience
325
     */
326
    @Override
327
    default @NotNull Iterable<? extends Audience> audiences() {
328
        return Collections.singleton(this.audience());
329
    }
330
}
331
```
332

333
### Audiences Utility Class
334

335
Factory methods and utilities for creating and working with audiences. Note that the main factory methods (`empty()`, `audience()`, `toAudience()`) are actually static methods on the `Audience` interface, not this utility class.
336

337
```java { .api }
338
/**
339
 * Utility class for audience operations and factories
340
 */
341
final class Audiences {
342
    /**
343
     * Creates an audience that will send a message to each audience
344
     * @param message the message to send
345
     * @return consumer that sends the message
346
     */
347
    static Consumer<? super Audience> sendingMessage(ComponentLike message);
348
}
349
```
350

351
**Usage Examples:**
352

353
```java
354
import net.kyori.adventure.audience.Audiences;
355
import java.util.Arrays;
356
import java.util.stream.Stream;
357

358
// Create composite audience
359
Audience broadcast = Audiences.audience(player1, player2, console);
360
broadcast.sendMessage(Component.text("Broadcast message"));
361

362
// Create audience from collection
363
List<Audience> playerList = getOnlinePlayers();
364
Audience allPlayers = Audiences.audience(playerList);
365

366
// Use collector to combine audiences
367
Audience adminBroadcast = admins.stream()
368
    .collect(Audiences.toAudience());
369
```
370

371
### Message Types
372

373
Enumeration of different message types for audience communication, affecting how messages are displayed and processed.
374

375
**⚠️ DEPRECATED**: MessageType is deprecated for removal in version 5.0.0. Use separate methods or ChatType.Bound instead.
376

377
```java { .api }
378
/**
379
 * Types of messages that can be sent to audiences
380
 * @deprecated for removal since 4.12.0, use separate methods or ChatType.Bound instead
381
 */
382
@Deprecated
383
enum MessageType {
384
    /**
385
     * A standard chat message
386
     * @deprecated for removal since 4.12.0
387
     */
388
    @Deprecated
389
    CHAT,
390
    
391
    /**
392
     * A system message (server announcements, etc.)
393
     * @deprecated for removal since 4.12.0
394
     */
395
    @Deprecated
396
    SYSTEM;
397
    
398
    /**
399
     * Gets the message type by ordinal
400
     * @param index the ordinal
401
     * @return the message type
402
     * @deprecated for removal since 4.12.0
403
     */
404
    @Deprecated
405
    static MessageType byOrdinal(int index);
406
}
407
```
408

409
## Identity and Pointer System
410

411
### Identified Interface
412

413
Interface for objects that have an identity, typically UUID-based.
414

415
```java { .api }
416
/**
417
 * Marks an object as having an identity
418
 */
419
interface Identified {
420
    /**
421
     * Gets the identity of this object
422
     * @return the identity
423
     */
424
    Identity identity();
425
}
426
```
427

428
### Identity Interface
429

430
Represents an entity's identity with UUID and name information.
431

432
```java { .api }
433
/**
434
 * Represents an identity with UUID and name
435
 */
436
interface Identity extends Examinable {
437
    /**
438
     * Gets the UUID of this identity
439
     * @return the UUID
440
     */
441
    UUID uuid();
442
    
443
    /**
444
     * Creates an identity from a UUID
445
     * @param uuid the UUID
446
     * @return new identity
447
     */
448
    static Identity identity(UUID uuid);
449
    
450
    /**
451
     * Creates a nil identity (all zeros UUID)
452
     * @return nil identity
453
     */
454
    static Identity nil();
455
}
456
```
457

458
### Pointered Interface
459

460
Interface for objects that can have metadata attached via pointers.
461

462
```java { .api }
463
/**
464
 * Objects that can have pointers attached
465
 */
466
interface Pointered {
467
    /**
468
     * Gets the pointers for this object
469
     * @return the pointers collection
470
     */
471
    @NotNull Pointers pointers();
472
    
473
    /**
474
     * Gets a value by pointer
475
     * @param pointer the pointer key
476
     * @return optional containing the value
477
     */
478
    default <T> @NotNull Optional<T> get(@NotNull Pointer<T> pointer) {
479
        return Optional.ofNullable(this.pointers().get(pointer));
480
    }
481
    
482
    /**
483
     * Gets a value by pointer with a default
484
     * @param pointer the pointer key
485
     * @param defaultValue the default value
486
     * @return the value or default
487
     */
488
    default <T> @Nullable T getOrDefault(@NotNull Pointer<T> pointer, @Nullable T defaultValue) {
489
        return this.pointers().get(pointer, defaultValue);
490
    }
491
    
492
    /**
493
     * Gets a value by pointer or computes it
494
     * @param pointer the pointer key
495
     * @param defaultValue supplier for default value
496
     * @return the value or computed default
497
     */
498
    default <T> @UnknownNullability T getOrDefaultFrom(@NotNull Pointer<T> pointer, @NotNull Supplier<? extends T> defaultValue) {
499
        return this.pointers().getOrDefaultFrom(pointer, defaultValue);
500
    }
501
}
502
```
503

504
### Pointer System
505

506
Type-safe key system for storing and retrieving typed values on pointered objects.
507

508
```java { .api }
509
/**
510
 * Type-safe key for storing typed values
511
 */
512
interface Pointer<T> extends Examinable {
513
    /**
514
     * Gets the type of values this pointer holds
515
     * @return the value type
516
     */
517
    Class<T> type();
518
    
519
    /**
520
     * Gets the key identifier
521
     * @return the key
522
     */
523
    Key key();
524
    
525
    /**
526
     * Creates a pointer
527
     * @param type the value type
528
     * @param key the key
529
     * @return new pointer
530
     */
531
    static <T> Pointer<T> pointer(Class<T> type, Key key);
532
    
533
    /**
534
     * Creates a pointer with string key
535
     * @param type the value type
536
     * @param key the key string
537
     * @return new pointer
538
     */
539
    static <T> Pointer<T> pointer(Class<T> type, String key);
540
}
541

542
/**
543
 * Collection of pointers with type-safe operations
544
 */
545
interface Pointers extends Examinable {
546
    /**
547
     * Checks if a pointer is supported
548
     * @param pointer the pointer
549
     * @return true if supported
550
     */
551
    <T> boolean supports(Pointer<T> pointer);
552
    
553
    /**
554
     * Gets a value by pointer
555
     * @param pointer the pointer
556
     * @return the value or null
557
     */
558
    <T> @Nullable T get(Pointer<T> pointer);
559
    
560
    /**
561
     * Creates an empty pointers collection
562
     * @return empty pointers
563
     */
564
    static Pointers empty();
565
    
566
    /**
567
     * Creates a builder for pointers
568
     * @return new builder
569
     */
570
    static Builder builder();
571
    
572
    interface Builder extends AbstractBuilder<Pointers> {
573
        /**
574
         * Sets a pointer value
575
         * @param pointer the pointer
576
         * @param value the value
577
         * @return this builder
578
         */
579
        <T> Builder withStatic(Pointer<T> pointer, T value);
580
        
581
        /**
582
         * Sets a dynamic pointer value
583
         * @param pointer the pointer
584
         * @param value the value supplier
585
         * @return this builder
586
         */
587
        <T> Builder withDynamic(Pointer<T> pointer, Supplier<T> value);
588
    }
589
}
590
```
591

592
## Permission System
593

594
### Permission Checker
595

596
Predicate-based interface for checking string-based permissions.
597

598
```java { .api }
599
/**
600
 * Permission checking interface
601
 */
602
interface PermissionChecker extends Predicate<String> {
603
    /**
604
     * Checks if a permission is granted
605
     * @param permission the permission string
606
     * @return true if permission is granted
607
     */
608
    @Override
609
    boolean test(String permission);
610
    
611
    /**
612
     * Creates a permission checker that always returns true
613
     * @return always-true checker
614
     */
615
    static PermissionChecker always();
616
    
617
    /**
618
     * Creates a permission checker that always returns false
619
     * @return always-false checker
620
     */
621
    static PermissionChecker never();
622
}
623
```
624

625
## Common Patterns
626

627
### Audience Filtering
628

629
```java
630
// Filter audiences based on permission
631
Audience permissionFiltered = allPlayers.filterAudience(audience -> 
632
    audience.get(PERMISSION_POINTER).test("some.permission"));
633

634
// Filter by location or other criteria
635
Audience nearbyPlayers = allPlayers.filterAudience(audience -> {
636
    Location loc = audience.get(LOCATION_POINTER);
637
    return loc != null && loc.distance(center) < 100;
638
});
639
```
640

641
### Broadcast Patterns
642

643
```java
644
// Create targeted broadcast
645
Audience admins = Audiences.audience(
646
    server.getPlayers().stream()
647
        .filter(player -> player.hasPermission("admin"))
648
        .collect(Audiences.toAudience())
649
);
650

651
// Send announcements
652
Audience everyone = Audiences.audience(players, console);
653
everyone.sendMessage(Component.text("Server restart in 5 minutes"));
654
```
655

656
### Message Formatting
657

658
```java
659
// Consistent message formatting
660
Component formatServerMessage(String content) {
661
    return Component.text()
662
        .append(Component.text("[SERVER] ", NamedTextColor.BLUE, TextDecoration.BOLD))
663
        .append(Component.text(content, NamedTextColor.WHITE))
664
        .build();
665
}
666

667
audience.sendMessage(formatServerMessage("Welcome to the server!"));
668
```