Logical Components
Relevant source files
The following files were used as context for generating this wiki page:
Logical Components are a set of special, non-visual components in the Farm Siege game engine. Unlike native components that render shapes or sprites to the canvas, logical components provide control flow, event handling, and structural organization. They are a key part of the engine's declarative, component-based architecture, allowing for complex behaviors like list rendering and user interaction to be managed cleanly within the component tree.
These components do not draw anything themselves but instead manage other components or interact with the engine's event system. The two primary logical components are Repeating and EventListener.
Repeating Component
The Repeating component is a powerful utility for rendering a dynamic list of child components. It iterates over an array of data and, for each item, renders a corresponding component with specified properties and position. This is essential for rendering collections of game objects like effects, bullets, or high score entries, where the number of items changes at runtime.
Sources: lib/components/logical/Repeating.ts
Properties
The behavior of the Repeating component is configured through its props:
| Prop | Type | Description |
|---|---|---|
list | any[] | The array of data items to iterate over. |
component | (data: any, index: number) => Component | A factory function that returns a new component instance for an item. |
position | (data: any, index: number) => Coordinates | A function that returns the Coordinates for the component based on the item's data and index. |
props | (data: any, index: number) => {} | A function that returns the props object to be passed to the child component for that item. |
Sources: lib/components/logical/Repeating.ts:9-14
Rendering Logic
On each render pass, the Repeating component performs several steps to efficiently manage its child components. It maintains an internal cache of component instances to avoid unnecessary re-creation.
The diagram below illustrates the rendering flow for the Repeating component.
This caching mechanism ensures that component state is preserved between frames as long as the item exists in the list. If the list shrinks, surplus component instances are removed.
Sources: lib/components/logical/Repeating.ts:22-51
Usage Examples
The Repeating component is used throughout the application to manage dynamic UI elements.
- Effects Overlay: Renders smoke and score effects based on the
effectsStore.
Sources: src/overlays/Effects.ts:14-43 - Highscores: Displays the list of high scores.
Sources: src/components/Highscores.ts:21-32 - Bullets: Renders all active bullets on the screen from the
characterStore.
Sources: src/overlays/Bullets.ts:14-28
EventListener Component
The EventListener component is an invisible component that captures user input, primarily clicks. It defines a rectangular area and executes a callback function when a click event occurs within its bounds. This is the primary mechanism for creating buttons and other interactive elements in the UI.
Sources: src/screens/StartScreen.ts:93-97, src/screens/HelpScreen.ts:128-132
Properties
| Prop | Type | Description |
|---|---|---|
size | Dimensions | The width and height of the clickable area. |
onClick | () => void | The callback function to execute on a click event. |
Sources: src/screens/StartScreen.ts:95-96, src/screens/HelpScreen.ts:130-131
Event Handling Flow
The EventListener works by intercepting events propagated through the component tree. The base Component class defines a propagateEvent method, which the EventListener likely overrides to implement its specific logic. When a click event is detected, it checks if the event coordinates fall within the size rectangle defined in its props. If the check passes, the onClick callback is invoked.
This sequence diagram shows how a user click on a button in the StartScreen is handled.
Usage Examples
EventListener is paired with visible components (like Sprite) to create the illusion of a button.
- Start Screen: Used for the "Play", "Help", "Cosmetics", and "Credits" buttons. Each
EventListeneris positioned over aSpritecomponent that displays the button's graphic.
Sources: src/screens/StartScreen.ts:93-143 - Help Screen: Manages the "Back", "Forward", and "Play"/"Home" navigation buttons for the instruction pages.
Sources: src/screens/HelpScreen.ts:128-169
Conclusion
The logical components Repeating and EventListener are fundamental to the farmsiege game engine. They abstract complex rendering and event-handling logic into simple, reusable components. This approach keeps the main component templates clean and declarative, separating concerns and making the overall architecture easier to understand and maintain. By handling dynamic lists and user interactions, they provide the core functionality needed for a rich, interactive user interface.