Getiyo-Public/Getiyo-Developer-Documentation

Table of Contents

ModuleClientAPI - Introduction

What Makes ModuleClientAPI Essential
Real-Time Property Updates
Seamless Communication
User-Centric Design
Module Scope and Safety

CSS and Sass Development

Timing and Synchronization
Integration with Getiyo's Ecosystem
Getting Started

ModuleClientAPI - Introduction

The ModuleClientAPI is the heart of every interactive Getiyo module's front-end experience. When users visit your channel and see your module in action, they're interacting with code powered by this comprehensive client-side interface. Think of it as your module's direct connection to the Getiyo ecosystem—enabling real-time communication with your server-side logic, responding instantly to property changes from the editor, and creating seamless user experiences that feel native to the platform.

What Makes ModuleClientAPI Essential

Every Getiyo module consists of two primary components: server-side logic that handles data processing and business rules, and client-side presentation that users actually see and interact with. The ModuleClientAPI bridges these two worlds, automatically establishing a persistent connection between your module's user interface and its corresponding ModuleServerAPI. This connection enables the real-time interactivity that makes Getiyo modules feel alive and responsive.

When you develop a module's user page, the ModuleClientAPI is automatically available as a global api object. This isn't just a simple communication tool—it's a comprehensive interface that understands Getiyo's unique architecture of scenes, displays, properties, and user management. Unlike traditional web development where you might manually handle WebSocket connections or polling for updates, the ModuleClientAPI abstracts away these complexities while providing powerful features specifically designed for Getiyo's live, collaborative environment.

Real-Time Property Updates

One of the most powerful features of the ModuleClientAPI is its ability to receive live property updates through api.onPropertyUpdate(). When someone editing a scene changes a color, updates text, or modifies any reference property of your module, those changes flow instantly to all connected viewers without requiring module redeployment or page refreshes. This creates an incredibly smooth content creation workflow where editors can see their changes reflected immediately across all displays.

This real-time capability extends beyond simple property updates. The ModuleClientAPI automatically handles the complexity of managing multiple module instances, ensuring that property updates reach the correct module references even when the same module type appears multiple times in a single scene. Your code simply registers listeners for the properties it cares about, and the API handles all the routing and synchronization behind the scenes.

Seamless Communication

Communication between your module's client and server components flows through intuitive message-passing methods. The api.send() function allows you to transmit any data to your server-side code, while api.on() lets you listen for responses or server-initiated messages. This bidirectional communication happens over persistent connections that the API manages automatically, including reconnection handling and message queuing during temporary network interruptions.

The communication system also supports interaction between neighboring modules through api.onNeighborMessage() and api.getNeighbors(). This enables sophisticated module ecosystems where different components can coordinate their behavior, share state, or trigger cascading effects across a scene.

User-Centric Design

Getiyo's strength lies in its understanding that every viewer is a unique user with specific capabilities, preferences, and context. The ModuleClientAPI provides deep integration with Getiyo's user management system through api.getUser(). Your module can access user details, check device capabilities, and adapt its interface accordingly—whether someone is viewing on a mobile device, has specific accessibility needs, or belongs to a particular organization.

The user integration goes beyond simple profile access. Methods like api.getUser().getName() can automatically prompt users to enter their name if they haven't already, creating seamless onboarding experiences. Camera and microphone access, mobile device detection, and user preference management are all handled through consistent, reliable interfaces that respect Getiyo's privacy and permission models.

Module Scope and Safety

Traditional web development often struggles with scope management when multiple components share a page. The ModuleClientAPI solves this elegantly by providing module-scoped access to DOM elements through api.dom(). Instead of using document.querySelector() which might accidentally select elements from other modules, you always query within your module's specific container. This prevents conflicts and ensures your module remains self-contained and reusable.

Similarly, instead of listening to global window resize events, you use api.onResize() to receive notifications when your specific module changes size. This module-scoped approach extends throughout the API, ensuring that your code remains robust even in complex scenes with multiple active modules.

CSS and Sass Development

The module scoping philosophy extends to your styling approach as well. While Getiyo provides automatic isolation between modules, you must structure your HTML and CSS properly to take advantage of this system. This means you should never write global CSS that targets elements like body, html, p, or h1 directly.

Instead, you need to create a main container element in your module's HTML with a descriptive class name, then scope all your CSS and Sass to that container:

<!-- In your module's index.html -->
<div class="my-awesome-module">
	<h1>My Module Title</h1>
	<div class="content-area">
		<button class="action-button">Click me</button>
	</div>
</div>

// ❌ NEVER do this - affects all modules globally
body {
	font-family: Arial, sans-serif;
}

h1 {
	color: red;
}

// ✅ ALWAYS scope to your module's container class
.my-awesome-module {
	font-family: Arial, sans-serif;

	h1 {
		color: red;
		font-size: 24px;
	}

	.content-area {
		padding: 20px;

		.action-button {
			background: blue;
			color: white;
			border: none;
			padding: 10px 20px;
			border-radius: 4px;
		}
	}
}

This scoping approach ensures that:

Multiple module instances can coexist without style conflicts
Different module types won't interfere with each other's appearance
Global Getiyo styling remains intact and functional
Module reusability is maintained across different scenes and channels

Remember that Getiyo provides global styling for module containers including backgrounds, filters, blending modes, borders, and padding. Your module's CSS should focus on the internal layout and styling of your content within your own container class, not these container-level properties that Getiyo manages automatically.

Timing and Synchronization

Live experiences require precise timing coordination across multiple displays and users. The ModuleClientAPI provides server-synchronized time through api.getTime(), ensuring that time-based animations, countdowns, and coordinated actions happen simultaneously across all viewers regardless of their local clock settings or network latency.

The API also includes sophisticated timing utilities through api.GameLib.Timing, offering easing functions, animation helpers, and frame-based timing tools that integrate seamlessly with Getiyo's rendering pipeline. These tools enable smooth, professional animations that feel native to the platform while maintaining perfect synchronization across all connected displays.

Integration with Getiyo's Ecosystem

The ModuleClientAPI doesn't exist in isolation—it's deeply integrated with Getiyo's broader ecosystem of cue lists, conditions, snapshots, and show control. Your module can participate in automated sequences by finishing client conditions with api.finishClientCondition(), respond to volume changes and play state updates, and maintain and recall states through the runtime storage system.

Global utilities like ce for quick element creation, Feedback for system-consistent notifications, and loading indicators ensure your module feels like a natural part of the Getiyo experience rather than a separate component.

Getting Started

Every module automatically has access to the ModuleClientAPI through the global api object. Your journey typically begins with setting up property listeners and communication handlers:

// React to property changes from the editor
api.onPropertyUpdate('backgroundColor', (color) => {
	api.dom().style.backgroundColor = color;
});

// Communicate with your server-side logic
api.send('userAction', { type: 'click' });

// Listen for server responses
api.on('updateDisplay', (data) => {
	// Update your module's presentation
});

The ModuleClientAPI transforms what could be complex, error-prone web development into an intuitive, powerful experience that lets you focus on creating engaging content rather than managing infrastructure. Whether you're building simple informational displays or complex interactive experiences, the API provides the foundation for professional, reliable modules that integrate seamlessly with Getiyo's live production environment.

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