# BridgeProtocol

**Repository Path**: TayunStarry/bridge-protocol

## Basic Information

- **Project Name**: BridgeProtocol
- **Description**: 统一推送协议（以下简称“协议”）是一个为基岩版游戏设计的通信协议，旨在标准化多核模组端之间的数据交换。该协议提供了一套灵活的接口，允许开发者轻松集成和扩展功能，实现模块化的数据推送。
- **Primary Language**: TypeScript
- **License**: MPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 7
- **Forks**: 0
- **Created**: 2024-11-16
- **Last Updated**: 2025-11-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: JavaScript, Server-API, TypeScript, Minecraft-Bedrock-Edition

## README

# BridgeProtocol
[中文](./README.md)
## Introduction
- The Unified Push Protocol (hereinafter referred to as "the Protocol") is a communication protocol designed for Bedrock Edition games, aiming to standardize data exchange between multiple mod packs.
- The protocol provides a set of flexible interfaces, allowing developers to easily integrate and expand features, achieving modular data pushing.

## Basic Information
- **Protocol Version**:
```
v1.0.4.24.11.15
```
- **Architecture Author**:
```
aa剑侠
```
- **Protocol Author**:
```
钛宇-星光阁
```
- **Release Date**:
```
2024-11-14
```
- **Contact Information**:
```
1965304849@qq.com
```

## Core Concepts

### Data Type Definitions
- **JSON Value Type (JSONValue)**: Supports strings, booleans, numbers, JSON objects, and JSON arrays.
- **JSON Object (JSONObject)**: A collection of key-value pairs, where the value can be any JSON value type.
- **JSON Array (JSONArray)**: An array of JSON value types.
- **Game Object Type (GameObject)**: Includes entities, blocks, players, dimensions, or item stacks.
- **Transmission Data Type (TransmissionDataType)**: Supports JSON values, game objects, and their arrays.

### Function Definitions
- **Export Function Type (ExportFunctionType)**: A function that accepts TransmissionDataType parameters and returns TransmissionDataType values.

### Event Listeners
- **Event Listener Interface (EventListener)**: Used for subscribing to and unsubscribing from event listening.

### Script Messages
- **Script Message Interface (ScriptMessage)**: Standardizes the message format when scripts are executed.

### Feature Implementation
- **Protocol Interceptor Class (ProtocolInterceptors)**: Handles custom logic before and after function calls.
- **Unified Push Protocol (BridgeProtocol)**: The core class, managing project identifiers, function lists, interceptors, and descriptive information.

### Helper Functions
- **Event Getter (eventGetter)**: Creates a Promise to wait for a specified event to occur.
- **Random Integer Generator (randomFloor)**: Generates a random integer within a specified range.
- **Simplified Serial Number Generator (BriefID)**: Generates a serial number based on timestamps and random numbers.

## Precautions
- This system is only a protocol and does not involve specific feature implementations.
- Each feature should be implemented independently by each mod.
- The push system only serves as a carrier for data pushing and does not involve data processing and storage.

## Usage Instructions

### Exporting Functions
Add/Update Features: Add or update functions to the feature list through the `exportFunction` method.

### Calling Functions
Asynchronous Calling: Use the `call` method to asynchronously call functions and wait for results.

### Data Conversion
Data Conversion Functions: Including `dataToArray`, `dataToTransmitString`, `typeConversion`, etc., used to convert server script event command messages into suitable transmission data types.

### String Representation
Game Object String Representation: Including `blockToString`, `entityToString`, `dimensionToString`, etc., used to convert game objects into string form.

## Usage Examples

### Creating a Protocol Instance:
```typescript
const bridge = new BridgeProtocol();
```

### Exporting Module Functions:
```typescript
< Format >
bridge.exportFunction(myFunction, "myFunctionName");
bridge.exportFunction(myFunction);

bridge.exportFunctions=[myFunction, "myFunctionName"];
bridge.exportFunctions=[myFunction];

bridge.exportFunctions=[
    [myFunction, "myFunctionName"],
    [myFunction, "myFunctionName"],
];
bridge.exportFunctions=[
    [myFunction],
    [myFunction],
];

< Example >
bridge.exportFunction((player: server.Player)=>{ player.sendMessage("Hello, World!"); }, "sayHello");
```

### Calling Module Functions:
```typescript
< Format >
bridge.call("myFunctionName", [arg1, arg2]);

< Example >
bridge.call("sayHello", [player]);
```

### Using Protocol Interceptors:
```typescript
bridge.protocolInterceptors.onCalled(func, functionName, parameters);
bridge.protocolInterceptors.onCalling(callback, functionName, parameters);
```

## Future Directions
- **Support More Game Object Types**: For example, support container data, item data, etc.
- **Support More Precise Duplex Communication**: For example, call a specific mod pack's function.
- **Support Cross-Mod Call Acceleration Reasoning**: For example, increase the priority for high-frequency called functions, prohibit unresponsive calls from being sent again at the call layer.

<img src="纳西妲.gif" alt="Bouncing Naxida" style="display: block; margin-left: auto; margin-right: auto;">