README.en.md
KCP is a high-performance, reliable transport protocol designed to significantly reduce latency compared to traditional TCP. It can achieve a 30–40% reduction in average latency and up to three times lower maximum delay, costing 10–20% additional bandwidth overhead.
KCP is implemented purely as an algorithm; it does not handle sending or receiving packets. It is designed to be transport-agnostic. Users must define their underlying transmission logic (e.g., via UDP) and pass data to KCP through callbacks. Even timekeeping is left to the user; KCP requires the current clock value to be provided externally, making it completely free of internal system calls.
The protocol consists of two source files: ikcp.h and ikcp.c. These files are lightweight and easy to integrate into your existing network stack. Whether you're building a P2P system or a UDP-based protocol that needs a robust ARQ (Automatic Repeat reQuest) mechanism, you can start using KCP by adding these files to your project and writing a few lines of integration code.
While TCP is optimized for throughput—maximizing the amount of data transmitted per second (e.g., kilobits/sec)—KCP is designed to focus on latency and packet delivery time. By prioritizing how quickly individual packets travel from sender to receiver, KCP trades 10–20% more bandwidth overhead for 30–40% faster transmission speed compared to TCP.
Think of TCP as a wide canal: it can carry a large volume of data, but the flow is relatively slow. In contrast, KCP is like a narrow, fast-moving stream—it sends smaller amounts of data more quickly, ensuring lower delay and faster responsiveness.
KCP supports both normal mode and fast mode, each optimizing performance based on different needs. Its increased flow rate is achieved through several key strategies:
In TCP, retransmission timeout (RTO) increases exponentially—each failure doubles the timeout interval (RTO × 2). This means three consecutive losses can escalate to RTO × 8, leading to serious transmission delays. KCP, in contrast, uses a more responsive approach in fast mode: the RTO increases by a factor of 1.5x (based on empirical results), significantly improving recovery speed and reducing delay after packet loss.
TCP often retransmits all subsequent data after a lost packet, which can lead to excessive redundancy. KCP implements selective retransmission, ensuring that only the actually lost packets are resent, minimizing unnecessary data transmission and improving efficiency.
When the sender transmits packets 1 through 5 and receives ACKs for 1, 3, 4, and 5, KCP deduces from missing ACK2 that packet 2 has likely been lost. After receiving multiple out-of-order ACKs, KCP can immediately trigger a fast retransmit of packet 2—without waiting for a timeout—drastically reducing retransmission latency under packet loss.
TCP often delays ACKs to optimize throughput, which can unintentionally inflate RTT calculations and delay loss detection—even with NODELAY settings.
KCP provides configurable ACK behavior, allowing ACKs to be sent immediately when needed, enhancing responsiveness in latency-sensitive applications.
ARQ protocols typically use either:
UNA (Unacknowledged Acknowledgment): Confirms all packets before a given sequence number (e.g., TCP).
ACK: Confirms receipt of a specific packet.
Each has tradeoffs: UNA can lead to full retransmissions, and standalone ACKs create overhead during loss. KCP combines both—each control message contains UNA info, and a dedicated ACK frame is used when necessary. This hybrid model increases reliability and precision without excess cost.
By default, KCP follows TCP's fair flow control—factoring in send buffer size, receiver buffer, congestion control, and slow-start. However, for latency-critical small data, KCP can be configured to bypass congestion and slow-start, relying only on buffer sizes. This allows smooth transmission even under heavy network load (e.g., when BitTorrent is active), sacrificing some fairness for timeliness.
You can download and install kcp using the vcpkg dependency manager:
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
./vcpkg install kcp
Microsoft team members and community contributors keep the kcp port in vcpkg up to date. If the version is outdated, please create an issue or pull request on the vcpkg repository.
Create KCP object:
// Initialize the kcp object, conv is an integer that represents the session number,
// same as the conv of tcp, both communication sides shall ensure the same conv,
// so that mutual data packets can be recognized, user is a pointer which will be
// passed to the callback function.
ikcpcb *kcp = ikcp_create(conv, user);
Set the callback function:
// KCP lower layer protocol output function, which will be called by KCP when it
// needs to send data, buf/len represents the buffer and data length.
// user refers to the incoming value at the time the kcp object is created to
// distinguish between multiple KCP objects
int udp_output(const char *buf, int len, ikcpcb *kcp, void *user)
{
....
}
// Set the callback function
kcp->output = udp_output;
Call update in an interval:
// Call ikcp_update at a certain frequency to update the kcp state, and pass in
// the current clock (in milliseconds). If the call is executed every 10ms, or
// ikcp_check is used to determine time of the next call for update, no need to
// call every time;
ikcp_update(kcp, millisec);
Input a lower layer data packet:
// Need to call when a lower layer data packet (such as UDP packet)is received:
ikcp_input(kcp, received_udp_packet, received_udp_size);
After processing the output/input of the lower layer protocols, the KCP protocol can work normally. ikcp_send is used to send data to the remote end, while the other end uses ikcp_recv (kcp, ptr, size) to receive the data.
The protocol default mode is a standard ARQ, and various acceleration switches can be enabled by configuration:
Working Mode:
int ikcp_nodelay(ikcpcb *kcp, int nodelay, int interval, int resend, int nc)
nodelay: Whether nodelay mode is enabled, 0 is not enabled; 1 enabled.interval ：P rotocol internal work interval, in milliseconds, such as 10 ms or 20 ms.resend ：Fast retransmission mode, 0 represents off by default, 2 can be set (2 ACK spans will result in direct retransmission)nc ： Whether to turn off flow control, 0 represents “Do not turn off” by default, 1 represents “Turn off”.Window Size:
int ikcp_wndsize(ikcpcb *kcp, int sndwnd, int rcvwnd);
By default, the call will set the maximum send window and maximum receive window size of the procotol, 32. This can be understood as SND_BUF and RCV_BUF of TCP, but the unit is not the same, SND / RCV_BUF unit is byte, while this unit is the packet.
Maximum Transmission Unit:
The algorithm protocol is not responsible for MTU detection. The default MTU is 1400 bytes, which can be set using ikcp_setmtu. The value will affect the maximum transmission unit upon data packet merging and fragmentation.
Minimum RTO:
No matter TCP or KCP, they have the limitation for the minimum RTO when calculating the RTO, even if the calculated RTO is 40ms, as the default RTO is 100ms, the protocol can only detect packet loss after 100ms, which is 30ms in the fast mode, and the value can be manually changed:
kcp->rx_minrto = 10;
Both the use and configuration of the protocol is straightforward, in most cases, after you read the above contents, you can use it. If you need further fine control, such as changing the KCP memory allocator, or if you need more efficient large-scale scheduling of KCP links (such as more than 3,500 links), or to better combine with TCP, you can continue the extensive reading:
If the network is never congested, KCP/TCP performance is similar; but the network itself is not reliable, and packet loss and jitter may be inevitable (otherwise why there are various reliable protocols). Compared in the intranet environment which is almost ideal, they have similar performance, but on the public Internet, under 3G / 4G network situation, or using the intranet packet loss simulation, the gap is obvious. The public network has an average of nearly 10% packet loss during peak times, which is even worse in wifi / 3g / 4g network, all of which will cause transmission congestion.
Thanks to zhangyuan the author of asio-kcp for the horizontal evaluation on KCP, enet and udt, and the conclusions are as follows:
For specifics please refer to: Reliable Udp Benchmark and KCP-Benchmark, for more guidance to the hesitant users.
MMO Engine SpatialOS has a benchmark report on KCP/TCP/RakNet:
for more details, please see the report itself:
See Success Stories.
Donation is welcome by using alipay, the money will be used to improve the protocol and documentation.
twitter: https://twitter.com/skywind3000 blog: http://www.skywind.me