-
Notifications
You must be signed in to change notification settings - Fork 19
Stock Components Legacy
Current Wiki index can be found here
xygine includes a few useful stock components by default. These are:
This allows animated sprites to be attached to an entity. Full control is provided via access to frame size, count, rate properties, and a utility class Animation provides management for ranges of different lengths / sizes inside a single sprite sheet. AnimatedDrawable also parses animation data stored in json formatted files, a simple editor for which, written in .net, is available as part of the xygine repository.
Control of animation triggers based on events is provided through a component which sits in the scene responding to custom messages and despatching commands to other nodes to play specific animations.
The audio listener represents the point in the world from which all audio sources are heard. When an audio source uses a mono sound file it is panned and attenuated (that is, faded with distance) based on its position relative to the audio listener. By default the audio listener of the scene is attached to the scene's starting camera, and therefore positioned at the centre of the screen. Creating a new AudioListener and attaching it to an entity will allow it to move around the scene. Normally you would attach the AudioListener to an entity with a custom camera, or perhaps the entity controlled by a player. There can only be one AudioListener instance in a scene, and creating a new one automatically removes the existing one. Be aware, however, that deliberately removing an AudioListener without replacing it may lead to errors playing back audio sources.
An audio source component is used to play back audio clips. Audio clips can either be 'cached' or 'streaming'. Large files such as music should be set to stream while smaller files such as sound effects can be cached. When a mono sound file is loaded in to an audio source attaching the AudioSource component to an entity will then pan and fade the audio clip based on the entity's transform relative to the active audio listener. Multiple AudioSource components can be attached to an entity, and each audio source component may have a custom message handler applied. This allows easy reaction to message events, such as playing a collision sound when a physics message is received. See message handlers for more detail.
Cameras can be attached to any entity in the scene so that they may take on their position and rotation in the world. To use a camera first create a camera component and attach it to an entity, before making it the scene's active camera. See Scene and Camera for more details.
A drawable component used to draw the 3D scene belonging to a MeshRenderer. Although the MeshRenderer can be drawn independently it is sometimes desirable to draw the 3D world within a specific layer in a Scene. This component can be attached to a node within a scene graph for this purpose. It is generally not recommended to have more than one of these components in a Scene from a performance perspective as it will cause the entire 3D scene to be drawn multiple times. In these cases it's better to draw the MeshRenderer directly to another buffer such as an sf::RenderTexture, and then use that texture with sprites placed within the Scene.
Using the model component 3D meshes can be rendered within a scene, attached to scene entities. For more information see MeshRenderer.
Similar to the AnimationController the ParticleController component is designed to sit in the scene graph attached to an entity, responding to events in the scene by firing particle systems which wouldn't normally be attached to any one single entity, such as explosions. Particle systems are defined via the ParticleSystem::Definition class which contains information about the properties of a particular particle system, such as emit rate or texture. Definitions can be manually configured in code, but also support loading json files, such as those output from utilities including the particle system editor, written in .net, found in the xygine repository. The ParticleController efficiently recycles existing systems for improved performance.
A highly flexible particle system which can be attached to any entity for effects such as explosions or trails. Particle systems can be controlled manually, or via events and commands despatched to the scene. Particle systems can be loaded from files defining their properties, or manually configured in code.
Point light components contain lighting information such as colour, intensity and falloff. Point lights adopt their parent entity's transform so can easily be made to move around the scene. As lights only represent the light data a lighting system must be used to render their effect. xygine includes a set of forward rendering shaders supporting point lighting with up to 8 active lights and optional normal mapping, but point light components are flexible enough to use with any custom lighting process. For example the xy::MultiRenderTexture class can be used to set up a deferred rendering system. Entities with a point light component are automatically spatially partitioned when added to a scene, so a set of visible lights can be quickly retreived from a given area using Scene::getVisibleLights().
Any entities with a QuadTreeComponent are added to the scene's quad tree for spatial partitioning, useful for collision queries and render culling. See Quad Tree.
While it's entirely possible (and can actually give better results) to write physics and collision detection from scratch using custom components, xygine also wraps the Box2D library and provides an interface via the component system. Adding a RigidBodyComponent to an entity allows its position and rotation to be updated by Box2D. Using the Box2D physics system is optional and xygine automatically creates the Box2D objects as needed - if no xy::Physics::World instance exists then there is zero overhead as Box2D is never invoked. The physics components also take care of all unit conversions, so that SFML coordinates can be used directly without worrying about the Box2D coordinate system. For more details see the Physics page.
A templated drawable component which allows easy wrapping of SFML drawables such as text, shapes or sprites. For example to attach a text object to an entity:
auto textComponent = xy::SfDrawableComponent<sf::Text>::create(messageBus);
auto& text = textComponent->getDrawable();
text.setFont(font);
text.setString("hello!");
entity->addComponent(textComponent);
When writing custom drawables, however, it is recommended to inherit directly from Component.
To compliment the audio source component, the SoundPlayer component allows easy triggering of one-shot sounds within a scene. Create a SoundPlayer component and use the preCache() function to map sounds to to SoundIDs and load them in to their own buffers. Then using the Message callback system to supply custom event handlers, or the Command system, trigger sounds such as laser fire or explosions at specific positions within the Scene. The sound player also features up to 16 channels to which sounds can be assigned, with each channel having its own independent volume control for flexible audio management. For instance game sound effects can be assigned to channel 1, and muted when displaying a menu which uses sounds on channel 8.
The SpriteBatch component (along with its Sprite counterpart) allows batching of sprites in to a single draw call. Sprites which belong to a batch must all share the texture used by the batch, although this is usually not a problem as a texture will often be an atlas created of many smaller textures. the xy::Sprite component of the SpriteBatch is marginally less flexible than the sf::Sprite as it does not carry its own transform, but it is generally not necessary as a sprite will be transformed by its parent Entity. To use a SpriteBatch component create it via the normal Component creation process:
auto batch = xy::Component::create<xy::SpriteBatch>(messageBus);
auto entity = xy::Entity::create(messageBus);
auto batchPtr = entity->addComponent(batch);
A sprite batch needs to be added to an entity belonging to a scene, as it is drawing this entity which draws all the associated sprites in a single call. Once the batch is created it can be configured and sprites created and added to thier own entities:
batchPtr->setTexture(myTextureAtlas);
auto sprite = batchPtr->addSprite(messageBus);
sprite->setTextureRect({0.f, 0.f, 30.f, 30.f}); //set a sub-rect of the atlas
auto spriteEntity = xy::Entity::create(messageBus);
spriteEntity->addComponent(sprite);
//...add other components
scene.addEntity(spriteEntity, xy::Scene::Layer::FrontMiddle);
Note that regardless to which layer the sprite entity is added the sprites will always be drawn on the layer to which the SpriteBatch component entity itself was added.
TileMapLayer components are drawables used to render a single layer of an Orthogonal map loaded by the tmx::Map class. TileMapLayer components cannot be created on their own, and must be created via the tmx::Map factory function getDrawable(). See tmx map support.