Configuration Reference EN

English · 简体中文

Configuration parameter reference

Target: 1.4.0. This lists public library tuning arguments, defaults, units, validation and scope. Application runtimes and benchmark CLI switches are separate. Configure listener builders before listen; configure socket policies after connect/accept. No policy is negotiated with the remote peer.

Parameter / API	Default / accepted values	Meaning and performance effect
bind address	explicit SocketAddr	IPv4/IPv6 and UDP port; port 0 requests an ephemeral port, available through local_addr(). Wildcard binding changes exposure, not peer authentication.
connect_with_version(..., raknet_version)	default 10; listener accepts 10/11	RakNet offline handshake version, not an application/game version. Unsupported versions can reject the handshake.
requested_mtu / maximum_mtu	default 1400 B; 61–1492 B	Nominal MTU; negotiation takes the smaller limit. 28 B IPv4/UDP reserve is not path-MTU discovery. Larger values reduce overhead but can increase path fragmentation/loss; smaller values increase frame overhead. Use socket.mtu() to inspect the negotiated value.
bind_with_receive_buffer_size(..., size)	NonZeroUsize, ≤ i32::MAX B	Per-socket OS receive buffer request, clamped by OS limits; failure returns SocketError. bind() requests 2 MiB best-effort; from_std() preserves supplied settings. More buffer can absorb bursts but cannot fix a stalled reader.
bind_with_socket_shards(..., count)	Linux; NonZeroUsize 1–64; default 1	Fixed SO_REUSEPORT receive group; 1 uses ordinary bind. Shards share identity, MOTD and backlog; does not parallelize one peer across all shards. Choose with worker count and flow distribution.
with_accept_backlog(backlog)	NonZeroUsize; default 128	Configure before listen or panic. Number of sessions awaiting accept, not maximum active connections; a full backlog delays offline handshakes until retry. Large queues can retain more pending sessions.
with_idle_maintenance(enabled) / set_idle_maintenance(enabled)	false	Listener builder applies to new accepted peers; socket setter changes that connection. After 500 ms quiet and empty queues, pause periodic maintenance; new work wakes it. Saves idle CPU but changes scheduling. Builder must precede listen.
with_receive_batching(enabled)	Linux; false	Before listen. Receive up to 16 ready datagrams without waiting for a full batch, on every shard. Evaluate busy throughput and sparse latency separately.
SendOptions::with_in_flight_limits(frames, bytes)	64 frames / 64 MiB; frames 1–4096; bytes 2048 B–64 MiB	Both limits bound unacknowledged reliable flight. Fragments and packed members count as separate frames; bytes include encoded frame overhead. Low limits can restrict high-RTT throughput; high limits can deepen bottleneck queues.
SendOptions::with_queue_budgets(reliable, unreliable)	256 KiB / 64 KiB; each ≥2048 B; sum ≤64 MiB	Reliable soft budget includes outstanding data; one large reliable send/batch can exceed it but must preserve the unreliable reserve. Unreliable has a separate pending budget. These are accounted bytes, not RSS or guaranteed bandwidth shares.
SendOptions::with_flush_budget(bytes)	256 KiB; 2048 B–64 MiB	Encoded-frame byte burst per scheduled flush. Must accommodate the connection MTU; applying incompatible options fails. Small budgets may defer work to another send, ACK or maintenance tick; no timer waits to collect messages.
set_send_options(options)	unconfigured until called; feature send-policy	Apply after connect/accept. Builders validate ranges; setter checks the negotiated MTU. Lowering limits retains queued/in-flight data. Default preset activates a policy, does not disable it; there is no reset-to-unconfigured API. Getters expose every configured limit.
RecoveryOptions::deadline_driven	false; feature recovery-policy	Earliest-retry wakeup; probe settings imply it even if this requested bool is false. Does not lower the RTO estimator.
RecoveryOptions::tail_probe_min_delay	None; Option	One complete eligible tail datagram replay. Wait at least max(1 ms, configured minimum, ceil(1.5 × SRTT)); millisecond precision. Requires fresh valid RTT, no queued data, no retransmission history. See recovery guide for fallback and performance effects.
RecoveryOptions::reset_backoff_on_progress	false; feature recovery-policy	Fresh unambiguous RTT feedback caps pending retry counts at one. Retransmitted ACKs do not qualify; does not reset Karn exclusion.
set_recovery_options(options)	all off by default	After connect/accept; getters return requested settings. Default resets runtime options, but the compiled timing correction remains. An active probe retains fallback.
send(..., reliability)	explicit; five modes	Per-message delivery semantics: Unreliable, UnreliableSequenced, Reliable, ReliableOrdered, ReliableSequenced. Payload starts with 0xfe. Only ReliableOrdered automatically fragments large outgoing data; other modes must fit MTU.
send_*_with_order_channel(..., order_channel)	default 0; u8 0–255	Independent ordered/sequenced streams; unordered modes do not encode this channel. Peer support may be narrower. Separation reduces cross-stream waiting, not shared-link congestion.
send_batch / send_bytes_batch messages	ready input; no collection timer	Small ReliableOrdered messages may pack up to eight frames per datagram within MTU. Other modes send individually. Real loss feedback/timeout disables future packing on that connection; ordinary send does not wait to collect batches.
recv_batch / recv_bytes_batch limit	0 returns immediately; work capped at 64	Wait for the first message, then drain ready messages up to min(limit,64); clear output first. Does not wait to fill the requested batch. Large limits increase uninterrupted application work.
set_full_motd(motd)	default generated MCPE-format string	Advertisement returned in offline pong, shared by listener shards. Must fit encoded offline response constraints; does not change handshake version or admission policy.
set_motd(name, max_connection, protocol, version, game_type, port)	explicit advertised fields	Build an MCPE-format MOTD. max_connection is an advertised maximum, not an enforced active-connection limit; protocol/version are application metadata, not RakNet handshake versions.
set_loss_rate(stage)	disabled initially; stage 0–10, larger values clamp to 10	Test-only simulated outgoing loss, in 10% steps; 0 loses none, 10 drops all. Not a WAN simulator or congestion controller. Use only an isolated test environment.
enable_raknet_log(flag)	0; bit mask 1 debug / 2 errors / 4 info	Process-wide logging categories; combine bits, e.g. 6 for errors+info. Debug formatting/output can affect throughput and latency.

Compile features and external controls

• send-policy exposes SendOptions and its setter/getter. Merely compiling it does not configure every connection; calling the setter activates the policy.
• recovery-policy exposes RecoveryOptions and its setter/getter. Defaults are off, but compiling it includes the timestamp correction even with all options off. Enable both with features = ["send-policy", "recovery-policy"] when needed.
• Tokio worker count is configured in the application runtime (Builder::worker_threads or application environment), not a library field. More workers can add contention; assess alongside socket shards.
• Addresses, application queue bounds, active-session admission and application deadlines belong to your application. Cancelling a send can leave already queued reliable data delivering; cancelling flush is not equivalent to closing.

Fixed implementation limits are not runtime knobs

Base RTO 50–12,000 ms, periodic maintenance 50 ms, receive inactivity timeout 60 s, message/frame accounting limits and reassembly bounds are internal constants without public setters. Changing public utils constants in an application does not reconfigure a compiled library. See protocol reference and messaging limits; neither send/recovery options nor MOTD size fields replace these limits. The low-level RaknetSocket::from takes an already negotiated MTU/version and dispatcher channels; normally use connect/accept rather than bypassing handshakes.

Recovery configuration · Send policy · Configuration examples

Blocking runtime and operation deadlines

Parameter / API	Default / values	Scope and performance effect
RaknetRuntime::with_worker_threads(workers)	NonZeroUsize; new() uses 1 worker	One shared Tokio runtime. More workers can handle parallel connections but add scheduling/contention; clone the runtime rather than create one per message.
Blocking *_timeout(..., duration)	Explicit Duration; non-timeout methods have no caller deadline	Deadline for that wait, not RTO, congestion control or rollback. Zero can time out immediately. Already queued sends may still deliver.
Async tokio::time::timeout(duration, future)	Application choice	Application deadline with an outer Elapsed error. Does not reconfigure transport retry timers.

blocking only exposes the adapter. It does not automatically enable send/recovery policy, batching or Linux receive optimizations. The listener builder's Linux restrictions and pre-listen requirements remain the same. Runtime construction and blocking waits reject Tokio context nesting.

Blocking guide · Feature combinations · Timeout semantics