@3dsource/types-unreal/README.md

A set of types for unreal module using in 3dsource projects

# @3dsource/types-unreal

A comprehensive collection of TypeScript type definitions for Unreal Engine integration. This library provides type
safety for communication between web applications and Unreal Engine.

## Overview

The types-unreal library offers:

- Type definitions for Unreal Engine commands and responses
- TypeScript interfaces for communication protocols
- Type-safe interaction with Unreal Engine from web applications
- Auto-generated types from Unreal Engine Commands API specifications

## Installation

### Prerequisites

- TypeScript 5.0+
- Node.js 20+
- npm 10+ (engines require `npm >9`)

### Peer Dependencies

This library requires the following peer dependency:

```json
{
  "@3dsource/unreal-commands-api-parser": ">=1.1.0"
}
```

### Library Installation

Install the library and ensure the peer dependency is available in your project:

```shell
npm i @3dsource/types-unreal @3dsource/unreal-commands-api-parser
```

## Usage

### Basic Import

Import the types you need in your TypeScript files:

```typescript
import type { UnrealCommands } from '@3dsource/types-unreal';
import type { MetaBoxCommandPacket } from '@3dsource/types-unreal';
import type { MetaBoxCommandList } from '@3dsource/types-unreal';
import type { FLoopBackCommand } from '@3dsource/types-unreal';
```

### Available Types

The library provides the following key type categories:

- Command Types — types for sending commands to Unreal Engine
- Response Types — types for handling responses from Unreal Engine
- Event Types — types for Unreal Engine events
- Data Structure Types — types for complex data structures used in communication

### Example Usage

```typescript
import type { UnrealCommands, MetaBoxCommandPacket } from '@3dsource/types-unreal';

// Type-safe command creation
const command: MetaBoxCommandPacket = {
  command: 'SetVisibility',
  parameters: {
    actorName: 'MyActor',
    visible: true,
  },
};

// Send command to Unreal Engine
function sendToUnreal(packet: MetaBoxCommandPacket) {
  // Implementation
}

sendToUnreal(command);
```

### Updating Types

Types in this package are auto-generated from the Unreal Engine Commands API using the
`@3dsource/unreal-commands-api-parser` peer dependency. The following scripts are available (see `package.json`):

- Production API → generates `src/lib/struct.ts`:

```shell
npm run generate:commands:prod
```

- QA API → generates `src/lib/struct.qa.ts`:

```shell
npm run generate:commands:qa
```

- Dev API → generates `src/lib/struct.dev.ts`:

```shell
npm run generate:commands:dev
```

Only `src/lib/struct.ts` is exported by the package public API (`src/public-api.ts`). The QA/Dev structures are
intended for development purposes and are not exported.

## Integration with Angular

This library works seamlessly with the `@3dsource/angular-unreal-module` for Angular applications:

```typescript
import { UnrealModule } from '@3dsource/angular-unreal-module';
import type { UnrealCommands } from '@3dsource/types-unreal';

// Your Angular module configuration
```

## Documentation

For detailed documentation of all available types, see the source code and comments in the type definition files.

## Notes

- Engines: `node >=20`, `npm >9` (see `engines` in `package.json`).
- Runtime dependency: `tslib` is included as a dependency of this package.