Entities

entities

Entities are arguably the most important part of the engine. Entities are first declared and defined, given their components, scripts, and default values, afterwhich they can be used to create entities in-game (through usage inside World tags). The following is an example of what an entity definition may look like:

<myEntity>
    <Position value="-200.0,50.0" />
    <Sprite>
        <frame>
            ....
        </frame>
    </Sprite>
    ...
</myEntity>

Then, to create an entity in-game (in the world XML file):

<World>
    ...
    <myEntity />
</World>

Entities can contain many different components, which will be listed and described below. These components are programmed into the engine, so entity ability is limited to what the engine can provide.

components

Components will simply be listed below, in some order of necessity (starting with most likely necessary).

default values

Values given in entity and component definitions are 'default', and will be applied to all creations of the entity unless overridden in-line. The engine has default 'default' values, but in most cases something should be specified.

position

An entity must have a position to exist.

<Position value="0.0,100.0" />

The default position value will determine where the entity spawns. If no coordinate is specified, the entity will spawn at any x coordinate within the world with a y of 150.

direction

I.e. velocity. Ideal to have if the entity needs to move.

<Direction />

solid

Allows an entity to have dimensions (width, height). Ideal to have.

<Solid />

physics

Allows gravity to act on the entity. Prevents falling through the world.

<Physics />

grounded

Forces an entity to stick to the ground. Useful for buildings, inanimate objects.

<Grounded />

portal

Intended for structures, allows the player to enter the thing into a new world.

<Portal />

sprite

Assigns a sprite/sprites to the entity, with support for limb separation. The Animation component requires multiple frames; however, the sprite component only requires a single frame to show when the entity is not moving.

<Sprite>
    <frame>
        <src limb="0" offset="0,0" size="12,24" drawOffset="0,0">path/to/image.png</src>
    </frame>
</Sprite>

A frame can contain multiple src's, or limbs. limb defines the limb number (used for animations), offset is the offset in the given image of the sprite, size is the size of the sprite, and drawOffset is the offset off of the entity to draw the sprite in-game.

animation

Requires the Sprite component. Allows entities to animate themselves when they move. Animations are constructed out of multiple frames, for each limb.

<Animation>
    <movement>
        <limb update="250.0" id="1">
            <frame>
                <src offset="0,0" size="12,24" drawOffset="12,0">path/to/image.png</src>
            </frame>
            ...
        </limb>
        ...
    </movement>
</Animation>

Each limb tag has an id, corresponding to the id given in the Sprite component; and an update attribute stating how fast to update the limb, in milliseconds. Frames are composed similar to how they were in the Sprite component, except to limb ids are needed.
Other types of animations may later be supported (via frames or with gif's).

name

Gives the entity a name. Shows under the entity in-game.

<Name value="Bob" />

dialog

Allows the entity to have dialog. Specific dialogs, text, and stuff are to be defined in the world XML file.

<Dialog />

health

Gives the entity an amount of health. Attacks only affect entities with health.

<Health value="100" />

aggro

Requires Wander to be effective. Allows an entity to be aggressive. Script in the Wander component can be used to toggle aggressiveness.

<Aggro />

wander

Allows the entity to wander or be aggressive (with the Aggro component). This component contains Lua script, which is further elaborated on in the Lua section of this wiki.

<Wander>
    update = function()
        ...
    end
</Wander>

Invalid Lua prevents any of the code within the component from working.

drop

Allows the entity to drop items upon death. Entities can drop any amount of items, within a given range.

<Drop>
    <item name="Item" min="1" max="5" />
    ...
</Drop>

Item names must come from the defined list in config/items.xml. min and max define the minimum and maximum quantities of the item the entity can produce.

trigger

Upon contact with an entity that has a trigger component, the screen goes to black and text is displayed. The entity dies upon exiting the blackout. Useful for cutscene-ing? Kinda?

<Trigger />