Components

Components are the building blocks for entities. They are simple containers for data and contain no logic.

Defining Components

To define components, import the Component type from the SDK and add fields of primitive values with known sizes.

import type { Component, u8, Vec2 } from '@vaguevoid/fiasco'

// GOOD
type Animal = Component<{
  speed: number
  health: u8
  extra: [cool: boolean, another: number]
  position: Vec2
}>

// BAD
type Animal = Component<{
  name: string // strings are not allowed. Must have a compile-time known size
  health: number[] // Array's with unknown length are not allowed
}>

// BAD
type Animal = Component<[something: number]> // Top level must be an object type

Once a component is defined, it can be used later for spawning and querying entities.

Valid Field Types

Component field types must have a known size at compile time, this is because the engine uses the size information of the component to efficiently organize how the data is stored during the game.

The SDK provides a few base primitive types, which can be combined to create larger struct-like component shapes.

Type	Size	Range	Alias
u8	1	0 to 255
i8	1	-128 to 127
u16	2	0 to 65,535
i16	2	-32,768 to 32,767
u32	4	0 to 4,294,967,295
i32	4	-2,147,483,648 to 2,147,483,647
u64	8	0 to 18,446,744,073,709,551,615
i64	8	-9,223,372,036,854,775,808 to 9,223,372,036,854,775,807	bigint
f32	4	1.2E-38 to 3.4E+38	number
f64	8	1.7E-308 to 1.7E+308
boolean	1	true to false

Sizing

The total size of the component is determined by adding the sizes of each field type.

For example, the following component is 7 bytes.

type Car = Component<{
  doors: u8        // 1 byte
  maxSpeed: number // 4 bytes
  batterySize: u16 // 2 bytes
}>

Generally, the smaller, the better.