ModuleServerAPI - Introduction

The ModuleServerAPI is the powerful server-side foundation that brings your Getiyo modules to life. Every module you create relies on this API to handle the complex orchestration between users, data, and the Getiyo platform itself.

What is the ModuleServerAPI?

Think of the ModuleServerAPI as your module's command center. While users interact with your module's visual interface through the ModuleClientAPI, the real magic happens server-side. This is where you process data, manage business logic, store sensitive information, and coordinate real-time experiences for multiple users simultaneously.

The ModuleServerAPI runs in a secure server environment, giving you access to powerful capabilities that would be impossible or unsafe to implement client-side. Whether you're building a simple display widget or a complex interactive experience, this API provides the tools to create responsive, scalable, and secure modules.

Core Capabilities

Real-time Communication: Instantly send messages to all connected clients or target specific users with api.broadcast() and api.getClient(). Your modules can respond to user interactions in real-time, creating engaging collaborative experiences.

Secure Property Management: Handle module properties defined in module.json that remain exclusively server-side — perfect for API keys, authentication tokens, sensitive configuration data, and persistent module state. Access and update these properties using api.getModuleProperty() and monitor changes with api.onModulePropertyUpdate(). While reference properties exist for scene-specific client-side data, your server-side logic should primarily rely on module properties for secure, persistent data management.

Rich File Operations: Read, write, and host files with full scope control through api.readJSON(), api.writeJSON(), and api.addHost(). Store module-specific data, share files across your channel, or serve static content directly to users.

Show Control Integration: Seamlessly integrate with Getiyo's cue list system using triggers and conditions. Register api.onTrigger() handlers to respond to automated cues, and use api.finishServerCondition() to control show flow based on your module's state.

External Service Integration: Connect to databases, APIs, and external services using battle-tested libraries like WebSocket, Redis, and Axios through api.Libs. Build modules that bridge Getiyo with your existing infrastructure.

How It Works

When your module loads, the ModuleServerAPI automatically connects to any ModuleClientAPI instances viewing your module. This creates a persistent, bidirectional communication channel that stays synchronized across scene changes, user interactions, and show control events.

Your server-side code registers event listeners to respond to messages from clients, module property updates from the admin interface, scene transitions, and triggers from cue lists. Meanwhile, you can push updates, broadcast changes, and maintain state that persists across user sessions.

Here's a simple example that demonstrates the API's event-driven nature:

// Respond to messages from any connected client
api.on('userAction', (client, actionData) => {
	console.log(`User ${client.getClientID()} performed action:`, actionData);

	// Process the action server-side
	const result = processUserAction(actionData);

	// Send response back to the specific user
	client.send('actionResult', result);

	// Broadcast the update to all other users
	const otherClients = Object.values(api.getClients()).filter(
		(c) => c.getClientID() !== client.getClientID()
	);

	otherClients.forEach((c) => {
		c.send('userUpdate', {
			user: client.getClientID(),
			action: actionData,
		});
	});
});

// Handle module property changes from the admin interface
api.onModulePropertyUpdate('apiKey', (newKey) => {
	console.log('API key updated, reconnecting to external service...');

	// Update external service connection with new credentials
	reconnectExternalService(newKey);

	// Notify all clients that service is reconnecting
	api.broadcast('serviceStatus', 'reconnecting');
});

// Respond to cue list triggers
api.onTrigger('startSequence', (finish, status, ...args) => {
	status('Starting sequence...');

	// Use module properties for configuration
	const sequenceConfig = api.getModuleProperty('sequenceSettings').getValue();

	// Perform the triggered action
	performSequence(args, sequenceConfig).then(() => {
		// Signal completion to continue the cue list
		finish();
	});
});

This introduction establishes the ModuleServerAPI's role and capabilities in a more narrative, welcoming tone while still providing concrete examples and clear

Introduction
GameLib
- Room
- Game
  - GamePlayer
  - Scoreboard
    - Details
    - State
- GameLib CollisionSpace

ModuleClientAPI

ModuleApi Shared

RuntimeStorage
Gamelib

ModuleServerAPI - Introduction

What is the ModuleServerAPI?

Core Capabilities

How It Works

Getting Started

Module Development

ModuleServerAPI

ModuleServerAPI GameLib

ModuleClientAPI

ModuleApi Shared