Bin

Overview

Bins are, simply put, objects that hold instanced components.

Components can't be instanced on their own and every instanced component must belong to a bin. Bins provide methods for managing components within it, as well as ways to tie their functionalities together.

local Health = require 'components.Health'

local bin = compost.newBin()
bin:addComponent(Health, 100) -- Pass 100 as a parameter to the init method

print(bin:expectComponent(Health):getHealth()) --> 100

Technically speaking, components can be retrieved from a bin directly, by indexing bin[Component] (in this example, bin[Health]:getHealth()), though this isn't recommended, as annotations won't work, and the methods provided by the bin for this purpose are more versatile.

Events

The bin manages listeners to events of other components in the same bin. The methods for this functionality are outlined below, but more information can be found on the Event page.

Methods

addComponent(component, ...)

Adds a new component to the bin, optionally passing in constructor parameters for the component's init method. If the component is already present in the bin, this function will throw an error.

removeComponent(component)

Removes the component from the bin. If the component isn't in the bin, nothing happens. Also removes any listeners the component might have attached to the bin.

getComponent(component)

Returns the component, or nil if it's not present in the bin.

forceComponent(component, ...)

If the component is present in the bin, simply returns it. If not, it first creates and adds it (optionally providing constructor arguments to its init method), guaranteeing the component will be present in the bin and returned.

expectComponent(component)

If the component is present in the bin, simply returns it. If not, throws an error.

addListener(event, component)

Adds the component as a listener to the given event. The component is expected to have the callback method for the event defined. If the component is already attached as a listener to the event, this function will error.

removeListener(event, component)

Removes the component from being a listener to the event. Does nothing if the component is not attached as a listener.

announce(event, ...)

Announces the event in the bin, with the given arguments. Will return the results from the listeners if a reducer function is set for the event.

clone()

Returns a deep copy of the bin.