⚡ Slipstream Engine (v2.0.0)
Slipstream 是 Minecraft (Paper) 中用于数据包拦截和物理模拟的下一代框架。
作为重型库(如 ProtocolLib)的超快现代化替代方案构建而成,专为 Kotlin 开发者设计,绝对专注于极致性能和生产级稳定性。
从 v2.0.0 开始,Slipstream 采用 多模块架构,直接从 NMS 自动生成 @JvmInline value class 包装器,提供 100% 类型安全、Java Records 支持以及零分配访问,且不污染全局命名空间。
? 为什么选择 Slipstream?
- ? 零反射字节码桥接: 使用
MethodHandles 和 Kotlin value classes。数据包以编译后的 JIT 字节码速度进行处理。
- ?️ 类型安全且整洁的 API: 忘掉
packet.isMovePacket() 吧。使用我们精心打造的 packet.wrapAs<WrapperMovePacket>(),它利用 inline reified 魔法保证零运行时开销,并提供整洁的自动补全作用域。
- ? 零分配嵌套结构: 为内部 NMS 类型(如
BlockPos、Vec3、ItemStack)自动生成包装器,确保不会在堆上不必要的实例化对象。
- ? 协程优先与惰性挂起: 直接在 Netty 线程中进行异步数据包处理。Slipstream 仅在监听器感兴趣时才启动协程,否则保持 100% 同步。
- ? 完整的数据包修改: 通过生成的可变字段 setter 轻松修改数据包,或通过
.copy() 修改不可变的 Java Records。
- ?️ 原生 Mojang 映射: 深度集成 Paper 的原生 Mojang 映射环境 (1.21+)。
? 文档与 Wiki
- ?️ 架构 — 多模块设计、代码生成及管道内部机制。
- ? API 指南 — 监听器、等待器 (
Awaiters)、wrapAs 及修饰器。
- ⏱️ 性能 — JMH 基准测试、内联重定义优化及 MethodHandles。
? 快速开始
Gradle (JitPack)
repositories {
maven("https://jitpack.io")
}
dependencies {
// 你只需要依赖核心模块,生成的包装器会自动拉取!
implementation("com.github.ClCody.Slipstream:slipstream-core:2.0.0")
}
? 使用示例 (API)
1. 类型安全转换 (wrapAs) 与同步监听器
Slipstream DX 的核心。在单一零开销行中检查并转换数据包:
val manager = SlipstreamPlugin.instance.manager
manager.registerListener(object : PacketListener {
override fun onPacketIn(player: Player, packet: Any): Boolean {
// 如果数据类型不匹配,wrapAs<T>() 将返回 null。
// 由 inline reified 驱动,因此零开销!
packet.wrapAs<WrapperServerboundMovePlayerPacket>()?.let { movePacket ->
val pos = movePacket.pos // 返回 WrapperBlockPos (零分配)
println("玩家移动到了 X: ${pos.x}, Y: ${pos.y}")
}
return true
}
})
2. 异步监听器 (挂起监听器)
不要阻塞服务器和 Netty!在处理数据包的同时进行数据库查询:
manager.registerSuspendListener(object : SuspendablePacketListener {
override fun interestsInbound(packet: Any): Boolean = packet.wrapAs<WrapperServerboundChatPacket>() != null
override suspend fun onPacketInSuspend(player: Player, packet: Any): Boolean {
// 协程可以挂起,后续数据包的顺序得到严格保留!
val isMuted = database.checkPlayerMute(player.uniqueId)
return !isMuted // false = 取消数据包
}
})
3. 数据包等待器
线性、非阻塞的数据包等待(例如,等待客户端事务):
// 向客户端发送事务
player.sendPacket(TransactionPacket(id = 1337))
// 协程会挂起,直到客户端发送带有目标 ID 的响应
val response = manager.awaitPacket<WrapperServerboundPongPacket>(player) {
it.packet.id == 1337
}
4. 修改数据包 (Setters 与 Records)
packet.wrapAs<WrapperClientboundSetEntityDataPacket>()?.let { dataPacket ->
// 使用生成的 MethodHandle setter 修改可变数据包
dataPacket.id = 999
}
packet.wrapAs<WrapperServerboundSwingPacket>()?.let { swingPacket ->
// 对于不可变的 Java Records,会生成一个 copy() 方法(就像 Kotlin 数据类一样)
val modified = swingPacket.copy(hand = InteractionHand.OFF_HAND)
}
? 许可证
MIT License。
⚡ Slipstream Engine (v2.0.0)
Slipstream is a Next-Gen framework for packet interception and physics simulation in Minecraft (Paper).
Built as an ultra-fast, modern alternative to heavy libraries (like ProtocolLib), designed specifically for Kotlin developers with an absolute focus on maximum performance and production stability.
Starting with v2.0.0, Slipstream utilizes a Multi-Module Architecture with automatic generation of @JvmInline value class wrappers directly from NMS, providing 100% type safety, Java Records support, and Zero-Allocation access without polluting the global namespace.
? Why Slipstream?
- ? Zero-Reflection Bytecode Bridge: Uses
MethodHandles and Kotlin value classes. Packets are processed at the speed of compiled JIT bytecode.
- ?️ Type-Safe & Clean API: Forget
packet.isMovePacket(). Use our beautifully crafted packet.wrapAs<WrapperMovePacket>() which uses inline reified magic to guarantee zero runtime overhead and a clean autocomplete scope.
- ? Zero-Allocation Nested Structures: Automatically generated wrappers for internal NMS types like
BlockPos, Vec3, ItemStack ensure no objects are unnecessarily instantiated in the heap.
- ? Coroutine-First & Lazy Suspend: Asynchronous packet processing directly in the Netty thread. Slipstream only launches coroutines when a listener is interested, otherwise, it stays 100% synchronous.
- ? Full Packet Mutation: Mutate packets easily via generated setters for mutable fields, or via
.copy() for immutable Java Records.
- ?️ Native Mojang Mappings: Deeply integrated with Paper's native Mojang-mapped environment (1.21+).
? Documentation & Wiki
- ?️ Architecture — Multi-module design, Code Generation, and Pipeline internals.
- ? API Guide — Listeners, Awaiters,
wrapAs, and Modifiers.
- ⏱️ Performance — JMH Benchmarks, Inline Reified optimizations, and MethodHandles.
? Quick Start
Gradle (JitPack)
repositories {
maven("https://jitpack.io")
}
dependencies {
// You only need to depend on the core module, the generated wrappers are pulled automatically!
implementation("com.github.ClCody.Slipstream:slipstream-core:2.0.0")
}
? Usage Examples (API)
1. Type-Safe Casts (wrapAs) & Synchronous Listeners
The core of Slipstream's DX. Check and cast a packet in one single zero-overhead line:
val manager = SlipstreamPlugin.instance.manager
manager.registerListener(object : PacketListener {
override fun onPacketIn(player: Player, packet: Any): Boolean {
// wrapAs<T>() returns null if it's the wrong packet.
// Powered by inline reified, so 0 overhead!
packet.wrapAs<WrapperServerboundMovePlayerPacket>()?.let { movePacket ->
val pos = movePacket.pos // Returns a WrapperBlockPos (zero-allocation)
println("Player moved to X: ${pos.x}, Y: ${pos.y}")
}
return true
}
})
2. Asynchronous Listeners (Suspend Listeners)
Don't block the server and Netty! Make database queries right during packet processing:
manager.registerSuspendListener(object : SuspendablePacketListener {
override fun interestsInbound(packet: Any): Boolean = packet.wrapAs<WrapperServerboundChatPacket>() != null
override suspend fun onPacketInSuspend(player: Player, packet: Any): Boolean {
// The coroutine can suspend, the order of following packets is strictly preserved!
val isMuted = database.checkPlayerMute(player.uniqueId)
return !isMuted // false = cancel packet
}
})
3. Packet Awaiter
Linear, non-blocking packet awaiting (e.g., waiting for client transactions):
// Send a transaction to the client
player.sendPacket(TransactionPacket(id = 1337))
// The coroutine suspends until the client sends a response with the target ID
val response = manager.awaitPacket<WrapperServerboundPongPacket>(player) {
it.packet.id == 1337
}
4. Modifying Packets (Setters & Records)
packet.wrapAs<WrapperClientboundSetEntityDataPacket>()?.let { dataPacket ->
// Modifying a mutable packet using generated MethodHandle setters
dataPacket.id = 999
}
packet.wrapAs<WrapperServerboundSwingPacket>()?.let { swingPacket ->
// For immutable Java Records, a copy() method is generated (just like Kotlin data classes)
val modified = swingPacket.copy(hand = InteractionHand.OFF_HAND)
}
? License
MIT License.
评论 0
登录后参与评分
还没有评论,来抢沙发吧