Object Properties and Attributes

Motivation

Defining and manipulating object properties is essential for creating dynamic and customizable games. This document outlines how to define and work with object properties and attributes in the context of the oglr library.

Defining Object Properties

Object properties are defined using the Property class. Properties can be of any type, including primitives, arrays, and objects.

import { Property } from 'oglr';
          
          // Define a property called 'position' with a default value of [0, 0, 0]
          const position = new Property({
              name: 'position',
              value: [0, 0, 0],
              type: 'array',
          });
          
          // Define a property called 'color' with a default value of [1, 1, 1]
          const color = new Property({
              name: 'color',
              value: [1, 1, 1],
              type: 'array',
          });
          
          // Define a property called 'enabled' with a default value of true
          const enabled = new Property({
              name: 'enabled',
              value: true,
              type: 'boolean',
          });
          

Property Options

Option	Description	Example
name	The name of the property.	name: 'position'
value	The initial value of the property.	value: [0, 0, 0]
type	The type of the property. (Supported types: 'array', 'object', 'boolean', 'number', 'string')	type: 'array'
readOnly	Whether the property can be modified after initialization (defaults to false).	readOnly: true
notify	Whether the property should notify listeners when its value changes (defaults to true).	notify: false
onChange	A callback function that will be called when the property value changes.	onChange: (newValue) => console.log(newValue)
onBeforeChange	A callback function that will be called before the property value changes.	onBeforeChange: (newValue) => console.log(newValue)

Example Usage

// Create a new object with the defined properties
          const myObject = {
              position,
              color,
              enabled,
          };
          
          // Access and modify the properties
          myObject.position.value = [1, 2, 3];
          myObject.color.value = [0, 0, 0];
          myObject.enabled.value = false;
          
          // Listen for changes to the properties
          myObject.position.onChange((newValue) => {
              console.log('Position changed:', newValue);
          });
          

Attributes

Attributes are used to define properties that can be used to control the appearance and behavior of objects. Attributes are associated with a specific Entity and can be accessed through the attributes property of the Entity.

import { Entity, Attribute } from 'oglr';
          
          // Create a new entity
          const entity = new Entity();
          
          // Define a position attribute
          const position = new Attribute({
              name: 'position',
              type: 'vec3',
          });
          
          // Add the attribute to the entity
          entity.attributes.add(position);
          
          // Access and modify the attribute values
          entity.attributes.get('position').value = [1, 2, 3];
          
          // Listen for changes to the attribute values
          entity.attributes.get('position').onChange((newValue) => {
              console.log('Position attribute changed:', newValue);
          });
          

Attribute Options

Option	Description	Example
name	The name of the attribute.	name: 'position'
type	The type of the attribute. (Supported types: 'float', 'vec2', 'vec3', 'vec4', 'mat4')	type: 'vec3'
size	The size of the attribute (number of components). (Defaults to the size of the type).	size: 2 (for a vec2 type)
normalized	Whether the attribute values should be normalized (defaults to false).	normalized: true
target	The target (usually a Mesh)	target: mesh

Example Usage

// Create a new mesh
          import { Mesh } from 'oglr';
          const mesh = new Mesh();
          
          // Define a position attribute
          const position = new Attribute({
              name: 'position',
              type: 'vec3',
              target: mesh,
          });
          
          // Add the attribute to the mesh
          mesh.attributes.add(position);
          
          // Set the attribute values
          mesh.attributes.get('position').value = [
              [1, 2, 3],
              [4, 5, 6],
              [7, 8, 9],
          ];
          

Conclusion

By leveraging the Property and Attribute classes, you can effectively define and manage game object properties and attributes, allowing for flexible customization and dynamic game development.