Skip to main content
The DefaultShardManagerBuilder is used to create and configure ShardManager instances with various settings for sharded Discord bots.

​
Creating a Builder

​
createDefault

Creates a builder with recommended default settings. 
static DefaultShardManagerBuilder createDefault(String token)
static DefaultShardManagerBuilder createDefault(String token, GatewayIntent intent, GatewayIntent... intents)
static DefaultShardManagerBuilder createDefault(String token, Collection<GatewayIntent> intents)
​
token
String
Your bot token
​
intents
Collection<GatewayIntent>
Gateway intents to enable
Default settings:
  • MemberCachePolicy: DEFAULT
  • ChunkingFilter: NONE
  • Intents: GatewayIntent.DEFAULT
  • Disables ACTIVITY and CLIENT_STATUS cache flags
Example: 
ShardManager manager = DefaultShardManagerBuilder
    .createDefault("YOUR_BOT_TOKEN")
    .build();

​
createLight

Creates a builder with minimal memory usage settings. 
static DefaultShardManagerBuilder createLight(String token)
static DefaultShardManagerBuilder createLight(String token, GatewayIntent intent, GatewayIntent... intents)
static DefaultShardManagerBuilder createLight(String token, Collection<GatewayIntent> intents)
Light profile settings:
  • MemberCachePolicy: NONE
  • ChunkingFilter: NONE
  • Disables all cache flags
  • Large threshold: 50
Example: 
ShardManager manager = DefaultShardManagerBuilder
    .createLight("YOUR_BOT_TOKEN")
    .enableIntents(GatewayIntent.GUILD_MESSAGES)
    .build();

​
create

Creates a builder with no defaults, maximum customization. 
static DefaultShardManagerBuilder create(GatewayIntent intent, GatewayIntent... intents)
static DefaultShardManagerBuilder create(Collection<GatewayIntent> intents)
static DefaultShardManagerBuilder create(String token, GatewayIntent intent, GatewayIntent... intents)
static DefaultShardManagerBuilder create(String token, Collection<GatewayIntent> intents)
​
token
String
Your bot token (can be set later with setToken())
​
intents
Collection<GatewayIntent>
required
Gateway intents to enable
Example: 
ShardManager manager = DefaultShardManagerBuilder
    .create("YOUR_BOT_TOKEN", GatewayIntent.GUILD_MESSAGES, GatewayIntent.MESSAGE_CONTENT)
    .setToken("YOUR_BOT_TOKEN")
    .setMemberCachePolicy(MemberCachePolicy.ALL)
    .build();

​
Basic Configuration

​
setToken

Sets the bot token. 
DefaultShardManagerBuilder setToken(String token)
​
token
String
required
Your Discord bot token

​
setShardsTotal

Sets the total number of shards. 
DefaultShardManagerBuilder setShardsTotal(int shardsTotal)
​
shardsTotal
int
required
Total number of shards (Discord recommends this value)
Discord provides the recommended shard count in the /gateway/bot endpoint. JDA automatically fetches this if not specified.

​
setShards

Sets specific shard IDs to run. 
DefaultShardManagerBuilder setShards(int... shardIds)
DefaultShardManagerBuilder setShards(Collection<Integer> shardIds)
​
shardIds
Collection<Integer>
required
Specific shard IDs to start
Example: 
// Run only shards 0, 1, and 2 out of 4 total
DefaultShardManagerBuilder.createDefault(token)
    .setShardsTotal(4)
    .setShards(0, 1, 2)
    .build();

​
Gateway Intents

​
enableIntents

Enables specific gateway intents. 
DefaultShardManagerBuilder enableIntents(GatewayIntent intent, GatewayIntent... intents)
DefaultShardManagerBuilder enableIntents(Collection<GatewayIntent> intents)
​
intents
Collection<GatewayIntent>
required
Intents to enable

​
disableIntents

Disables specific gateway intents. 
DefaultShardManagerBuilder disableIntents(GatewayIntent intent, GatewayIntent... intents)
DefaultShardManagerBuilder disableIntents(Collection<GatewayIntent> intents)
Example: 
DefaultShardManagerBuilder.createDefault(token)
    .enableIntents(GatewayIntent.MESSAGE_CONTENT)
    .disableIntents(GatewayIntent.GUILD_PRESENCES)
    .build();

​
setEnabledIntents

Sets the exact set of enabled intents. 
DefaultShardManagerBuilder setEnabledIntents(Collection<GatewayIntent> intents)

​
Cache Configuration

​
enableCache

Enables specific cache flags. 
DefaultShardManagerBuilder enableCache(CacheFlag flag, CacheFlag... flags)
DefaultShardManagerBuilder enableCache(Collection<CacheFlag> flags)
​
flags
Collection<CacheFlag>
required
Cache flags to enable

​
disableCache

Disables specific cache flags. 
DefaultShardManagerBuilder disableCache(CacheFlag flag, CacheFlag... flags)
DefaultShardManagerBuilder disableCache(Collection<CacheFlag> flags)
Example: 
DefaultShardManagerBuilder.createDefault(token)
    .enableCache(CacheFlag.VOICE_STATE)
    .disableCache(CacheFlag.ACTIVITY, CacheFlag.CLIENT_STATUS)
    .build();

​
setMemberCachePolicy

Configures member caching policy. 
DefaultShardManagerBuilder setMemberCachePolicy(MemberCachePolicy policy)
​
policy
MemberCachePolicy
The member caching policy (default: ALL)
Example: 
// Only cache members in voice channels
DefaultShardManagerBuilder.createDefault(token)
    .setMemberCachePolicy(MemberCachePolicy.VOICE)
    .build();

// Cache members with specific roles
MemberCachePolicy policy = (member) -> 
    member.getRoles().stream()
        .anyMatch(role -> role.getName().equals("Moderator"));

DefaultShardManagerBuilder.createDefault(token)
    .setMemberCachePolicy(policy)
    .build();

​
setChunkingFilter

Configures guild member chunking. 
DefaultShardManagerBuilder setChunkingFilter(ChunkingFilter filter)
​
filter
ChunkingFilter
required
Determines which guilds to chunk members for
Example: 
// Chunk all guilds
DefaultShardManagerBuilder.createDefault(token)
    .setChunkingFilter(ChunkingFilter.ALL)
    .build();

// Don't chunk any guilds
DefaultShardManagerBuilder.createDefault(token)
    .setChunkingFilter(ChunkingFilter.NONE)
    .build();

​
Event Listeners

​
addEventListeners

Adds global event listeners to all shards. 
DefaultShardManagerBuilder addEventListeners(Object... listeners)
DefaultShardManagerBuilder addEventListeners(Collection<Object> listeners)
​
listeners
Object...
required
Event listeners (must implement EventListener)
Example: 
DefaultShardManagerBuilder.createDefault(token)
    .addEventListeners(new MyEventListener())
    .build();

​
addEventListenerProvider

Adds shard-specific event listeners via a provider. 
DefaultShardManagerBuilder addEventListenerProvider(IntFunction<Object> listenerProvider)
DefaultShardManagerBuilder addEventListenerProviders(Collection<IntFunction<Object>> listenerProviders)
​
listenerProvider
IntFunction<Object>
required
Function that receives shard ID and returns a listener
Example: 
DefaultShardManagerBuilder.createDefault(token)
    .addEventListenerProvider(shardId -> new ShardListener(shardId))
    .build();

​
setEventManagerProvider

Sets a custom event manager for each shard. 
DefaultShardManagerBuilder setEventManagerProvider(IntFunction<? extends IEventManager> eventManagerProvider)
Example: 
DefaultShardManagerBuilder.createDefault(token)
    .setEventManagerProvider(shardId -> new AnnotatedEventManager())
    .build();

​
Presence Configuration

​
setActivity

Sets the activity for all shards. 
DefaultShardManagerBuilder setActivity(Activity activity)
​
activity
Activity
The activity to display
Example: 
DefaultShardManagerBuilder.createDefault(token)
    .setActivity(Activity.playing("with shards"))
    .build();

​
setActivityProvider

Sets shard-specific activities. 
DefaultShardManagerBuilder setActivityProvider(IntFunction<? extends Activity> activityProvider)
Example: 
DefaultShardManagerBuilder.createDefault(token)
    .setActivityProvider(shardId -> 
        Activity.playing("Shard " + shardId)
    )
    .build();

​
setStatus

Sets the online status for all shards. 
DefaultShardManagerBuilder setStatus(OnlineStatus status)

​
setStatusProvider

Sets shard-specific online statuses. 
DefaultShardManagerBuilder setStatusProvider(IntFunction<OnlineStatus> statusProvider)

​
setIdle

Sets the idle state for all shards. 
DefaultShardManagerBuilder setIdle(boolean idle)

​
Advanced Configuration

​
setSessionController

Sets a custom session controller for managing shard connections. 
DefaultShardManagerBuilder setSessionController(SessionController controller)
​
controller
SessionController
Session controller for coordinating shard connections

​
setVoiceDispatchInterceptor

Sets a custom voice dispatch handler. 
DefaultShardManagerBuilder setVoiceDispatchInterceptor(VoiceDispatchInterceptor interceptor)
​
interceptor
VoiceDispatchInterceptor
Custom voice dispatch interceptor

​
setAudioModuleConfig

Configures the audio module. 
DefaultShardManagerBuilder setAudioModuleConfig(AudioModuleConfig config)
​
config
AudioModuleConfig
Audio module configuration

​
setCompression

Sets the gateway compression algorithm. 
DefaultShardManagerBuilder setCompression(Compression compression)
​
compression
Compression
required
Compression type (default: ZLIB)

​
setGatewayEncoding

Sets the gateway encoding format. 
DefaultShardManagerBuilder setGatewayEncoding(GatewayEncoding encoding)
​
encoding
GatewayEncoding
required
Encoding format (default: JSON)

​
Behavioral Flags

​
setAutoReconnect

Enables/disables automatic reconnection. 
DefaultShardManagerBuilder setAutoReconnect(boolean autoReconnect)
​
autoReconnect
boolean
required
true to enable auto-reconnect (default)

​
setBulkDeleteSplittingEnabled

Enables/disables splitting bulk delete events. 
DefaultShardManagerBuilder setBulkDeleteSplittingEnabled(boolean enabled)
​
enabled
boolean
required
true to split bulk deletes into individual events (default)

​
setEnableShutdownHook

Enables/disables the JVM shutdown hook. 
DefaultShardManagerBuilder setEnableShutdownHook(boolean enable)
​
enable
boolean
required
true to enable shutdown hook (default)

​
setRawEventsEnabled

Enables raw gateway events. 
DefaultShardManagerBuilder setRawEventsEnabled(boolean enable)
​
enable
boolean
required
true to fire RawGatewayEvent for all events

​
setEventPassthrough

Enables raw data passthrough on events. 
DefaultShardManagerBuilder setEventPassthrough(boolean enable)
​
enable
boolean
required
true to include raw DataObject in events

​
Thread Pool Configuration

​
setCallbackPoolProvider

Sets the thread pool for RestAction callbacks. 
DefaultShardManagerBuilder setCallbackPoolProvider(ThreadPoolProvider<? extends ExecutorService> provider)

​
setGatewayPoolProvider

Sets the thread pool for gateway operations. 
DefaultShardManagerBuilder setGatewayPoolProvider(ThreadPoolProvider<? extends ScheduledExecutorService> provider)

​
setRateLimitSchedulerProvider

Sets the thread pool for rate limit scheduling. 
DefaultShardManagerBuilder setRateLimitSchedulerProvider(ThreadPoolProvider<? extends ScheduledExecutorService> provider)

​
Building

​
build

Builds and starts the ShardManager. 
ShardManager build() throws LoginException, InvalidTokenException
​
returns
ShardManager
The configured ShardManager instance
Example: 
ShardManager manager = DefaultShardManagerBuilder
    .createDefault("YOUR_BOT_TOKEN")
    .setActivity(Activity.watching("the shards"))
    .addEventListeners(new MyListener())
    .build();

​
Complete Example

public class ShardedBot {
    public static void main(String[] args) throws Exception {
        ShardManager shardManager = DefaultShardManagerBuilder
            .createDefault(
                "YOUR_BOT_TOKEN",
                GatewayIntent.GUILDS,
                GatewayIntent.GUILD_MESSAGES,
                GatewayIntent.MESSAGE_CONTENT
            )
            // Cache configuration
            .setMemberCachePolicy(MemberCachePolicy.VOICE)
            .enableCache(CacheFlag.VOICE_STATE)
            .disableCache(CacheFlag.ACTIVITY, CacheFlag.CLIENT_STATUS)
            
            // Event listeners
            .addEventListeners(new GlobalListener())
            .addEventListenerProvider(shardId -> new ShardListener(shardId))
            
            // Presence
            .setActivityProvider(shardId ->
                Activity.playing("Shard " + shardId)
            )
            .setStatus(OnlineStatus.ONLINE)
            
            // Advanced configuration
            .setAutoReconnect(true)
            .setCompression(Compression.ZLIB)
            .setBulkDeleteSplittingEnabled(false)
            
            .build();
        
        System.out.println("ShardManager started with " + 
                          shardManager.getShardsTotal() + " shards");
    }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us