@dcl/sdk 7.20.2-22104870534.commit-0df3cc0 → 7.20.2-22169778016.commit-030cbfe

package/src/network/message-bus-sync.ts

@@ -1,27 +1,53 @@
-import { IEngine, Transport, RealmInfo, PlayerIdentityData } from '@dcl/ecs'
+import { IEngine, Transport, RealmInfo } from '@dcl/ecs'
 import { type SendBinaryRequest, type SendBinaryResponse } from '~system/CommunicationsController'
 
 import { syncFilter } from './filter'
 import { engineToCrdt } from './state'
-import { BinaryMessageBus, CommsMessage, decodeString, encodeString } from './binary-message-bus'
+import { BinaryMessageBus, CommsMessage } from './binary-message-bus'
 import { fetchProfile } from './utils'
 import { entityUtils } from './entities'
+import { createServerValidator } from './server'
 import { GetUserDataRequest, GetUserDataResponse } from '~system/UserIdentity'
 import { definePlayerHelper } from '../players'
 import { serializeCrdtMessages } from '../internal/transports/logger'
+import { IsServerRequest, IsServerResponse } from '~system/EngineApi'
+import { Atom } from '../atom'
+import { setGlobalRoom, Room } from './events/implementation'
 
 export type IProfile = { networkId: number; userId: string }
 // user that we asked for the inital crdt state
+export const AUTH_SERVER_PEER_ID = 'authoritative-server'
+export const DEBUG_NETWORK_MESSAGES = () => (globalThis as any).DEBUG_NETWORK_MESSAGES ?? false
+
+// Test environment detection without 'as any'
+const isTestEnvironment = (): boolean => {
+  try {
+    if (typeof globalThis === 'undefined') return false
+    const globalWithProcess = globalThis as unknown as { process?: { env?: { NODE_ENV?: string } } }
+    return globalWithProcess.process?.env?.NODE_ENV === 'test'
+  } catch {
+    return false
+  }
+}
+
 export function addSyncTransport(
   engine: IEngine,
   sendBinary: (msg: SendBinaryRequest) => Promise<SendBinaryResponse>,
-  getUserData: (value: GetUserDataRequest) => Promise<GetUserDataResponse>
+  getUserData: (value: GetUserDataRequest) => Promise<GetUserDataResponse>,
+  isServerFn: (request: IsServerRequest) => Promise<IsServerResponse>,
+  name: string
 ) {
-  const DEBUG_NETWORK_MESSAGES = () => (globalThis as any).DEBUG_NETWORK_MESSAGES ?? false
   // Profile Info
   const myProfile: IProfile = {} as IProfile
   fetchProfile(myProfile!, getUserData)
 
+  const isServerAtom = Atom<boolean>()
+  const isRoomReadyAtom = Atom<boolean>(false)
+
+  void isServerFn({}).then(($: IsServerResponse) => {
+    return isServerAtom.swap(!!$.isServer)
+  })
+
   // Entity utils
   const entityDefinitions = entityUtils(engine, myProfile)
 
@@ -40,108 +66,196 @@ export function addSyncTransport(
   const players = definePlayerHelper(engine)
 
   let stateIsSyncronized = false
-  let transportInitialzed = false
 
+  /**
+   * We need to wait till 2 ticks that is when the engine is ready to send new messages.
+   * The first tick is for the client engine processing the CRDT messages,
+   * and the second one are the messages created by the main() function.
+   * So to avoid sending those messages, that all the clients have, through the network we put this validation here.
+   */
+  let tick = 0
+  const TRANSPORT_INITIALIZED_NUMBER = isTestEnvironment() ? 0 : 2
   // Add Sync Transport
   const transport: Transport = {
     filter: syncFilter(engine),
     send: async (messages) => {
-      for (const message of [messages].flat()) {
-        if (message.byteLength && transportInitialzed) {
+      if (tick <= TRANSPORT_INITIALIZED_NUMBER) tick++
+      for (const message of tick > TRANSPORT_INITIALIZED_NUMBER ? [messages].flat() : []) {
+        if (message.byteLength) {
           DEBUG_NETWORK_MESSAGES() &&
             console.log(...Array.from(serializeCrdtMessages('[NetworkMessage sent]:', message, engine)))
-          binaryMessageBus.emit(CommsMessage.CRDT, message)
+
+          // Convert regular messages to network messages for broadcasting with chunking
+          for (const chunk of serverValidator.convertRegularToNetworkMessage(message)) {
+            binaryMessageBus.emit(CommsMessage.CRDT, chunk)
+          }
         }
       }
       const peerMessages = getMessagesToSend()
-      let totalSize = 0
-      for (const message of peerMessages) {
-        for (const data of message.data) {
-          totalSize += data.byteLength
-        }
-      }
-      if (totalSize) {
-        DEBUG_NETWORK_MESSAGES() && console.log('Sending network messages: ', totalSize / 1024, 'KB')
-      }
       const response = await sendBinary({ data: [], peerData: peerMessages })
       binaryMessageBus.__processMessages(response.data)
-      transportInitialzed = true
     },
-    type: 'network'
+    type: name
   }
+
+  // Server validation setup
+  const serverValidator = createServerValidator({
+    engine,
+    binaryMessageBus
+  })
+
+  // Initialize Event Bus with registered schemas
+  const eventBus = new Room(engine, binaryMessageBus, isServerAtom, isRoomReadyAtom)
+
+  // Set global eventBus instance
+  setGlobalRoom(eventBus)
+
   engine.addTransport(transport)
   // End add sync transport
 
   // Receive & Process CRDT_STATE
-  binaryMessageBus.on(CommsMessage.RES_CRDT_STATE, (value) => {
-    const { sender, data } = decodeCRDTState(value)
-    if (sender !== myProfile.userId) return
+  binaryMessageBus.on(CommsMessage.REQ_CRDT_STATE, async (data, sender) => {
+    DEBUG_NETWORK_MESSAGES() && console.log('[REQ_CRDT_STATE]', sender, Date.now())
+    for (const chunk of engineToCrdt(engine)) {
+      DEBUG_NETWORK_MESSAGES() && console.log('[Emiting:]', sender, Date.now())
+      binaryMessageBus.emit(CommsMessage.RES_CRDT_STATE, chunk, [sender])
+    }
+  })
+  binaryMessageBus.on(CommsMessage.RES_CRDT_STATE, async (data, sender) => {
+    requestingState = false
+    elapsedTimeSinceRequest = 0
+    if (isServerAtom.getOrNull() || sender !== AUTH_SERVER_PEER_ID) return
     DEBUG_NETWORK_MESSAGES() && console.log('[Processing CRDT State]', data.byteLength / 1024, 'KB')
-    transport.onmessage!(data)
+    transport.onmessage!(serverValidator.processClientMessages(data, sender))
     stateIsSyncronized = true
-  })
-
-  // Answer to REQ_CRDT_STATE
-  binaryMessageBus.on(CommsMessage.REQ_CRDT_STATE, async (_, userId) => {
-    DEBUG_NETWORK_MESSAGES() && console.log(`Sending CRDT State to: ${userId}`)
 
-    for (const chunk of engineToCrdt(engine)) {
-      binaryMessageBus.emit(CommsMessage.RES_CRDT_STATE, encodeCRDTState(userId, chunk), [userId])
+    // IMPORTANT: Only mark room as ready AFTER state is synchronized
+    // This ensures comms is truly connected and working
+    const realmInfo = RealmInfo.getOrNull(engine.RootEntity)
+    if (realmInfo && checkRoomReady(realmInfo)) {
+      DEBUG_NETWORK_MESSAGES() && console.log('[isRoomReady] Marking room as ready after state sync')
+      isRoomReadyAtom.swap(true)
     }
   })
 
-  // Process CRDT messages here
-  binaryMessageBus.on(CommsMessage.CRDT, (value) => {
+  // received message from the network
+  binaryMessageBus.on(CommsMessage.CRDT, (value, sender) => {
+    const isServer = isServerAtom.getOrNull()
     DEBUG_NETWORK_MESSAGES() &&
-      console.log(Array.from(serializeCrdtMessages('[NetworkMessage received]:', value, engine)))
-    transport.onmessage!(value)
-  })
-
-  async function requestState(retryCount: number = 1) {
-    let players = Array.from(engine.getEntitiesWith(PlayerIdentityData))
-    DEBUG_NETWORK_MESSAGES() && console.log(`Requesting state. Players connected: ${players.length - 1}`)
-
-    if (!RealmInfo.getOrNull(engine.RootEntity)?.isConnectedSceneRoom) {
-      DEBUG_NETWORK_MESSAGES() && console.log(`Aborting Requesting state?. Disconnected`)
-      return
+      console.log(
+        transport.type,
+        ...Array.from(serializeCrdtMessages('[NetworkMessage received]:', value, engine)),
+        isServer
+      )
+    if (isServer) {
+      transport.onmessage!(serverValidator.processServerMessages(value, sender))
+    } else if (sender === AUTH_SERVER_PEER_ID) {
+      // Process network messages from server and convert to regular messages
+      transport.onmessage!(serverValidator.processClientMessages(value, sender))
     }
+  })
 
-    binaryMessageBus.emit(CommsMessage.REQ_CRDT_STATE, new Uint8Array())
+  // received authoritative message from server - force apply to fix invalid local state
+  binaryMessageBus.on(CommsMessage.CRDT_AUTHORITATIVE, (value, sender) => {
+    // Only accept authoritative messages from authoritative server
+    if (sender !== AUTH_SERVER_PEER_ID) return
 
-    // Wait ~5s for the response.
-    await sleep(5000)
+    // DEBUG_NETWORK_MESSAGES() &&
+    console.log('[AUTHORITATIVE] Received authoritative message from server:', value.byteLength, 'bytes')
 
-    players = Array.from(engine.getEntitiesWith(PlayerIdentityData))
+    // Process authoritative messages by forcing them through normal CRDT processing
+    // but with a timestamp that's guaranteed to be accepted
+    const authoritativeBuffer = serverValidator.processClientMessages(value, sender, true)
+    if (authoritativeBuffer.byteLength > 0) {
+      // Apply authoritative message through normal transport, but the server's messages
+      // should be processed as authoritative with special timestamp handling
+      transport.onmessage!(authoritativeBuffer)
 
-    if (!stateIsSyncronized) {
-      if (players.length > 1 && retryCount <= 2) {
-        DEBUG_NETWORK_MESSAGES() &&
-          console.log(`Requesting state again ${retryCount} (no response). Players connected: ${players.length - 1}`)
-        void requestState(retryCount + 1)
-      } else {
-        DEBUG_NETWORK_MESSAGES() && console.log('No active players. State syncronized')
-        stateIsSyncronized = true
-      }
+      DEBUG_NETWORK_MESSAGES() && console.log('[AUTHORITATIVE] Applied server authoritative message to local state')
     }
-  }
+  })
 
   players.onEnterScene((player) => {
     DEBUG_NETWORK_MESSAGES() && console.log('[onEnterScene]', player.userId)
+    if (!isServerAtom.getOrNull() && myProfile.userId === player.userId) {
+      requestState()
+    }
   })
 
+  // Helper to check room ready conditions
+  function checkRoomReady(realmInfo: ReturnType<typeof RealmInfo.getOrNull>): boolean {
+    if (!realmInfo) return false
+
+    try {
+      // Check if room instance exists
+      if (!eventBus) return false
+
+      return !!(realmInfo.commsAdapter && realmInfo.isConnectedSceneRoom && realmInfo.room)
+    } catch {
+      return false
+    }
+  }
+
   // Asks for the REQ_CRDT_STATE when its connected to comms
   RealmInfo.onChange(engine.RootEntity, (value) => {
+    const isServer = isServerAtom.getOrNull()
+
     if (!value?.isConnectedSceneRoom) {
-      DEBUG_NETWORK_MESSAGES() && console.log('Disconnected from comms')
-      stateIsSyncronized = false
+      // Only react when actually transitioning from ready to not ready
+      if (isRoomReadyAtom.getOrNull() === true) {
+        DEBUG_NETWORK_MESSAGES() && console.log('Disconnected from comms')
+        isRoomReadyAtom.swap(false)
+        if (!isServer) {
+          stateIsSyncronized = false
+        }
+      }
     }
 
     if (value?.isConnectedSceneRoom) {
-      DEBUG_NETWORK_MESSAGES() && console.log('Connected to comms')
+      requestState()
+
+      // For servers, mark as ready immediately when connected
+      // (servers don't need to sync state from anyone)
+      if (isServer && checkRoomReady(value) && isRoomReadyAtom.getOrNull() === false) {
+        DEBUG_NETWORK_MESSAGES() && console.log('[isRoomReady] Server marking room as ready')
+        isRoomReadyAtom.swap(true)
+      }
+      // For clients, room will be marked ready after receiving CRDT state (above)
     }
+  })
 
-    if (value?.isConnectedSceneRoom && !stateIsSyncronized) {
-      void requestState()
+  let requestingState = false
+  let elapsedTimeSinceRequest = 0
+  const STATE_REQUEST_RETRY_INTERVAL = 2.0 // seconds
+
+  /**
+   * Why we have to request the state if we have a server that can send us the state when we joined?
+   * The thing is that when the server detects a new JOIN_PARTICIPANT on livekit room, it sends automatically the state to that peer.
+   * But in unity, it takes more time, so that message is not being delivered to the client.
+   * So instead, when we are finally connected to the room, we request the state, and then the server answers with the state :)
+   *
+   * If no response is received within 2 seconds, the request is automatically retried.
+   */
+  function requestState() {
+    if (isServerAtom.getOrNull()) return
+    if (RealmInfo.getOrNull(engine.RootEntity)?.isConnectedSceneRoom && !requestingState) {
+      requestingState = true
+      elapsedTimeSinceRequest = 0
+      DEBUG_NETWORK_MESSAGES() && console.log('Requesting state...')
+      binaryMessageBus.emit(CommsMessage.REQ_CRDT_STATE, new Uint8Array())
+    }
+  }
+
+  // System to retry state request if no response is received within the retry interval
+  engine.addSystem((dt: number) => {
+    if (requestingState && !stateIsSyncronized) {
+      elapsedTimeSinceRequest += dt
+      if (elapsedTimeSinceRequest >= STATE_REQUEST_RETRY_INTERVAL) {
+        DEBUG_NETWORK_MESSAGES() && console.log('State request timed out, retrying...')
+        elapsedTimeSinceRequest = 0
+        requestingState = false
+        requestState()
+      }
     }
   })
 
@@ -153,56 +267,12 @@ export function addSyncTransport(
     return stateIsSyncronized
   }
 
-  function sleep(ms: number) {
-    return new Promise<void>((resolve) => {
-      let timer = 0
-      function sleepSystem(dt: number) {
-        timer += dt
-        if (timer * 1000 >= ms) {
-          engine.removeSystem(sleepSystem)
-          resolve()
-        }
-      }
-      engine.addSystem(sleepSystem)
-    })
-  }
-
   return {
     ...entityDefinitions,
     myProfile,
-    isStateSyncronized
+    isStateSyncronized,
+    binaryMessageBus,
+    eventBus,
+    isRoomReadyAtom
   }
 }
-
-/**
- * Messages Protocol Encoding
- *
- * CRDT: Plain Uint8Array
- *
- * CRDT_STATE_RES { sender: string, data: Uint8Array}
- */
-function decodeCRDTState(data: Uint8Array) {
-  let offset = 0
-  const r = new Uint8Array(data)
-  const view = new DataView(r.buffer)
-  const senderLength = view.getUint8(offset)
-  offset += 1
-  const sender = decodeString(data.subarray(1, senderLength + 1))
-  offset += senderLength
-  const state = r.subarray(offset)
-
-  return { sender, data: state }
-}
-
-function encodeCRDTState(address: string, data: Uint8Array) {
-  // address to uint8array
-  const addressBuffer = encodeString(address)
-  const addressOffset = 1
-  const messageLength = addressOffset + addressBuffer.byteLength + data.byteLength
-
-  const serializedMessage = new Uint8Array(messageLength)
-  serializedMessage.set(new Uint8Array([addressBuffer.byteLength]), 0)
-  serializedMessage.set(addressBuffer, 1)
-  serializedMessage.set(data, addressBuffer.byteLength + 1)
-  return serializedMessage
-}

package/src/network/server/index.ts

@@ -0,0 +1,301 @@
+import {
+  IEngine,
+  Entity,
+  CrdtMessageType,
+  CrdtMessageBody,
+  ProcessMessageResultType,
+  ComponentType,
+  PutNetworkComponentOperation
+} from '@dcl/ecs'
+import * as components from '@dcl/ecs/dist/components'
+import { ReadWriteByteBuffer } from '@dcl/ecs/dist/serialization/ByteBuffer'
+import { CommsMessage } from '../binary-message-bus'
+import { chunkCrdtMessages } from '../chunking'
+import * as utils from './utils'
+import { AUTH_SERVER_PEER_ID, DEBUG_NETWORK_MESSAGES } from '../message-bus-sync'
+import { type BinaryMessageBus } from '../binary-message-bus'
+import {
+  LastWriteWinElementSetComponentDefinition,
+  GrowOnlyValueSetComponentDefinition,
+  ComponentDefinition,
+  InternalBaseComponent
+} from '@dcl/ecs/dist/engine/component'
+
+export const LIVEKIT_MAX_SIZE = 12
+
+export interface ServerValidationConfig {
+  engine: IEngine
+  binaryMessageBus: ReturnType<typeof BinaryMessageBus>
+}
+
+export function createServerValidator(config: ServerValidationConfig) {
+  const { engine, binaryMessageBus } = config
+
+  // Initialize components for network operations and transform fixing
+  const NetworkEntity = components.NetworkEntity(engine)
+  const CreatedBy = components.CreatedBy(engine)
+  const NetworkParent = components.NetworkParent(engine)
+
+  // Type guard to check if component supports corrections (both LWW and GrowOnlySet)
+  function supportsCorrections<T>(
+    component: ComponentDefinition<T>
+  ): component is LastWriteWinElementSetComponentDefinition<T> | GrowOnlyValueSetComponentDefinition<T> {
+    return (
+      (component.componentType === ComponentType.LastWriteWinElementSet ||
+        component.componentType === ComponentType.GrowOnlyValueSet) &&
+      'getCrdtState' in component
+    )
+  }
+
+  function findExistingNetworkEntity(message: utils.NetworkMessage): Entity | null {
+    // Look for existing network entity mapping (don't create new ones)
+    for (const [entityId, networkData] of engine.getEntitiesWith(NetworkEntity)) {
+      if (networkData.networkId === message.networkId && networkData.entityId === message.entityId) {
+        return entityId
+      }
+    }
+    // Return null if not found
+    return null
+  }
+
+  function findOrCreateNetworkEntity(message: utils.NetworkMessage, sender: string, isServer: boolean): Entity {
+    // Look for existing network entity mapping first
+    const existingEntity = findExistingNetworkEntity(message)
+
+    if (existingEntity) {
+      return existingEntity
+    }
+
+    // Create new entity and network mapping
+    const newEntityId = engine.addEntity()
+    NetworkEntity.createOrReplace(newEntityId, {
+      networkId: message.networkId,
+      entityId: message.entityId
+    })
+
+    if (isServer) {
+      CreatedBy.createOrReplace(newEntityId, { address: sender })
+    }
+
+    DEBUG_NETWORK_MESSAGES() &&
+      console.log(`[DEBUG] Created new entity ${newEntityId} for network ${message.networkId}:${message.entityId}`)
+    return newEntityId
+  }
+
+  function convertNetworkToRegularMessage(
+    networkMessage: utils.NetworkMessage,
+    localEntityId: Entity,
+    forceCorrections = false
+  ): (CrdtMessageBody & { messageBuffer: Uint8Array }) | null {
+    const buffer = new ReadWriteByteBuffer()
+
+    try {
+      // Use the well-tested networkMessageToLocal utility with transform fixing for Unity
+      const message = utils.networkMessageToLocal(
+        networkMessage,
+        localEntityId,
+        buffer,
+        NetworkParent,
+        forceCorrections
+      )
+      return { ...message, messageBuffer: buffer.toBinary() }
+    } catch (error) {
+      DEBUG_NETWORK_MESSAGES() && console.error('Error converting network message:', error)
+      return null
+    }
+  }
+
+  function validateMessagePermissions(message: utils.RegularMessage, sender: string, _localEntityId: Entity): boolean {
+    // Basic checks
+    if (!sender || sender === AUTH_SERVER_PEER_ID) {
+      return false // Server shouldn't send messages to itself
+    }
+
+    if (message.type === CrdtMessageType.DELETE_ENTITY) {
+      // TODO: how to handle this case ?
+    }
+
+    if (message.type === CrdtMessageType.PUT_COMPONENT || message.type === CrdtMessageType.DELETE_COMPONENT) {
+      const component = engine.getComponent(message.componentId) as InternalBaseComponent<unknown>
+      const buf = 'data' in message ? new ReadWriteByteBuffer(message.data) : null
+      const value = buf ? component.schema.deserialize(buf) : null
+      const dryRunCRDT = component.__dry_run_updateFromCrdt(message)
+      const validCRDT = [
+        ProcessMessageResultType.StateUpdatedData,
+        ProcessMessageResultType.StateUpdatedTimestamp,
+        ProcessMessageResultType.EntityDeleted
+      ].includes(dryRunCRDT)
+      const createdBy = CreatedBy.getOrNull(message.entityId)
+      const validMessage =
+        validCRDT &&
+        component.__run_validateBeforeChange(message.entityId, value, sender, createdBy?.address ?? AUTH_SERVER_PEER_ID)
+
+      return !!validMessage
+    }
+
+    // For now, basic validation - in the future this will check component sync permissions
+    // TODO: Check if sender owns the entity
+    // TODO: Check component sync mode ('all' | 'owner' | 'server')
+    // TODO: Run component custom validation
+    return true
+  }
+
+  function broadcastBatchedMessages(messages: utils.NetworkMessage[], excludeSender: string) {
+    if (messages.length === 0) return
+
+    // Build the complete buffer with all messages
+    const networkBuffer = new ReadWriteByteBuffer()
+    for (const message of messages) {
+      // Skip oversized messages upfront
+      if (message.messageBuffer.byteLength / 1024 > LIVEKIT_MAX_SIZE) {
+        console.error(
+          `Message too large (${message.messageBuffer.byteLength} bytes), skipping message from ${excludeSender}`
+        )
+        continue
+      }
+      networkBuffer.writeBuffer(message.messageBuffer, false)
+    }
+
+    // Use the chunking function to split into proper chunks
+    const chunks = chunkCrdtMessages(networkBuffer.toBinary(), LIVEKIT_MAX_SIZE)
+
+    for (const chunk of chunks) {
+      binaryMessageBus.emit(CommsMessage.CRDT, chunk)
+    }
+    DEBUG_NETWORK_MESSAGES() &&
+      console.log(`Total: ${messages.length} messages in ${chunks.length} chunks from ${excludeSender}`)
+  }
+
+  function sendCorrectionToSender(networkMessage: utils.NetworkMessage, sender: string, localEntityId: Entity) {
+    try {
+      // Only handle component messages (PUT/DELETE), not entity deletion
+      if (networkMessage.type === CrdtMessageType.DELETE_ENTITY_NETWORK) {
+        DEBUG_NETWORK_MESSAGES() && console.log('[AUTHORITATIVE] Cannot send authoritative message for entity deletion')
+        return
+      }
+
+      // Safe to access componentId and timestamp now
+      const component = engine.getComponent(networkMessage.componentId)
+
+      // Only proceed if component supports authoritative messages (LWW or GrowOnlySet)
+      if (!supportsCorrections(component)) {
+        DEBUG_NETWORK_MESSAGES() && console.log('[AUTHORITATIVE] Component does not support authoritative messages')
+        return
+      }
+
+      const serverCRDTState = component.getCrdtState(localEntityId)
+
+      if (serverCRDTState) {
+        // Create authoritative message using PUT_COMPONENT_NETWORK
+        // Each client will convert this to AUTHORITATIVE_PUT_COMPONENT with proper entity mapping
+        const correctionBuffer = new ReadWriteByteBuffer()
+        PutNetworkComponentOperation.write(
+          networkMessage.entityId, // Use original network entity ID
+          serverCRDTState.timestamp,
+          networkMessage.componentId,
+          networkMessage.networkId,
+          serverCRDTState.data,
+          correctionBuffer
+        )
+        // Send authoritative message directly to the sender
+        binaryMessageBus.emit(CommsMessage.CRDT_AUTHORITATIVE, correctionBuffer.toBinary(), [sender])
+
+        DEBUG_NETWORK_MESSAGES() &&
+          console.log(
+            `[AUTHORITATIVE] Sent authoritative message to ${sender} for entity ${localEntityId} component ${networkMessage.componentId} with timestamp ${networkMessage.timestamp}`
+          )
+      }
+    } catch (error) {
+      DEBUG_NETWORK_MESSAGES() && console.error('Error sending correction:', error)
+    }
+  }
+
+  return {
+    findExistingNetworkEntity,
+    // transform Network messages to CRDT Common Messages.
+    processClientMessages: function processClientMessages(value: Uint8Array, sender: string, forceCorrections = false) {
+      // console.log(`[CLIENT] Processing message from ${sender}, ${value.length} bytes`)
+
+      // Collect all regular messages in a single buffer for batched application
+      const combinedBuffer = new ReadWriteByteBuffer()
+
+      // Clients process network messages from server and convert them to regular messages
+      for (const message of utils.readMessages(value)) {
+        // Only process network messages in client message handler
+        if (utils.isNetworkMessage(message)) {
+          const networkMessage = message as utils.NetworkMessage
+
+          // Find or create network entity mapping
+          const localEntityId = findOrCreateNetworkEntity(networkMessage, sender, false)
+
+          // Convert network message to regular message or correction message
+          const regularMessage = convertNetworkToRegularMessage(networkMessage, localEntityId, forceCorrections)
+
+          if (regularMessage?.messageBuffer.byteLength) {
+            combinedBuffer.writeBuffer(regularMessage.messageBuffer, false)
+          }
+        }
+      }
+      return combinedBuffer.toBinary()
+    },
+    // Sever Code: process message, handle permissions, and broadcast if needed.
+    processServerMessages: function processServerMessages(value: Uint8Array, sender: string) {
+      // console.log(`[SERVER] Processing message from ${sender}, ${value.length} bytes`)
+
+      // Collect all valid messages for batched broadcasting
+      const messagesToBroadcast: utils.NetworkMessage[] = []
+      const regularMessagesBuffer = new ReadWriteByteBuffer()
+
+      for (const message of utils.readMessages(value)) {
+        try {
+          // Only process network messages in server message handler
+          if (utils.isNetworkMessage(message)) {
+            const networkMessage = message as utils.NetworkMessage
+            // 1. Find or create network entity mapping
+            const localEntityId = findOrCreateNetworkEntity(networkMessage, sender, true)
+
+            // 2. Convert network message to regular message and collect for local application
+            const regularMessage = convertNetworkToRegularMessage(networkMessage, localEntityId)
+
+            // 3. Basic permission validation
+            if (!validateMessagePermissions(regularMessage as any, sender, localEntityId)) {
+              // Send correction back to sender with server's authoritative state
+              sendCorrectionToSender(networkMessage, sender, localEntityId)
+              continue
+            }
+
+            // 4. Collect valid message for batched broadcasting
+            messagesToBroadcast.push(networkMessage)
+
+            if (regularMessage?.messageBuffer.byteLength) {
+              regularMessagesBuffer.writeBuffer(regularMessage.messageBuffer, false)
+            }
+          }
+        } catch (error) {
+          DEBUG_NETWORK_MESSAGES() && console.error('Error processing server message:', error)
+        }
+      }
+      // Batch broadcast all valid messages together
+      broadcastBatchedMessages(messagesToBroadcast, sender)
+      return regularMessagesBuffer.toBinary()
+    },
+    // engine changes that needs to be broadcasted.
+    convertRegularToNetworkMessage: function convertRegularToNetworkMessage(regularMessage: Uint8Array): Uint8Array[] {
+      const groupedBuffer = new ReadWriteByteBuffer()
+
+      // First pass: Convert all regular messages to network format and group them into one big buffer
+      for (const message of utils.readMessages(regularMessage)) {
+        // Only convert regular messages that have network data
+        const networkData = NetworkEntity.getOrNull(message.entityId)
+
+        if (networkData && !utils.isNetworkMessage(message)) {
+          utils.localMessageToNetwork(message, networkData, groupedBuffer)
+        }
+      }
+
+      // Second pass: Use the new chunking function that respects message boundaries
+      const totalData = groupedBuffer.toBinary()
+      return chunkCrdtMessages(totalData, LIVEKIT_MAX_SIZE)
+    }
+  }
+}