### Engine Application Entry Points in Haskell

Source: https://context7.com/keid/engine/llms.txt

Demonstrates various ways to start the Keid Engine application using the `engineMain` and `engineMainWith` functions. These functions handle Vulkan initialization, window creation, and the main render loop, accepting an initial stage definition.

```Haskell
import Engine.App (engineMain, engineMainWith, withDataDir, withDefaultArgs)
import Engine.Types (Stage(..), StackStage(..))

-- Simple application entry point
main :: IO ()
main = engineMain myInitialStage

-- Entry point with custom initialization
main :: IO ()
main = engineMainWith
  (\config -> myStageFromConfig config)
  (loadConfiguration "config.yaml")

-- Run with data directory and default arguments
main :: IO ()
main =
  withDataDir getDataDir "data" $ 
    withDefaultArgs [("--msaa", Just "4")] $ 
      engineMain myStage
```

--------------------------------

### Headless Rendering Setup

Source: https://context7.com/keid/engine/llms.txt

Enables headless rendering without a window for offline processing using Vulkan. It involves setting up a headless Vulkan context and provides access to Vulkan resources like the device, allocator, and queues. Rendering operations can be performed using the HasVulkan instance.

```haskell
import Engine.Setup (setupHeadless, Headless(..))

-- Set up headless Vulkan context
headless@Headless{..} <- setupHeadless defaultOptions

-- Access Vulkan resources
let device = hDevice
let allocator = hAllocator
let queues = hQueues

-- Use HasVulkan instance for rendering operations
runReaderT renderOffscreen headless

```

--------------------------------

### Buffer Management: Allocate, Update, and Observe Buffers

Source: https://context7.com/keid/engine/llms.txt

This section covers the buffer management module, which handles GPU memory allocation for various data types. It explains how to create coherent (CPU-visible) and staged (GPU-only) buffers, update their contents, and set up observers for automatic updates. It also includes examples of peeking and poking individual elements in coherent buffers.

```haskell
import Resource.Buffer
import qualified Data.Vector.Storable as VectorS

-- Allocate a coherent buffer (CPU-visible, automatically synchronized)
(bufferKey, vertexBuffer) <- allocateCoherent
  (Just "Vertex Buffer")           -- debug label
  Vk.BUFFER_USAGE_VERTEX_BUFFER_BIT
  1000                             -- initial capacity
  (VectorS.fromList vertices)

-- Update coherent buffer contents
updatedBuffer <- updateCoherent newVertices vertexBuffer

-- Update with automatic resize if needed
resizedBuffer <- updateCoherentResize_ vertexBuffer largerData

-- Create staged buffer (GPU-only, requires transfer)
stagedBuffer <- createStaged
  (Just "Index Buffer")
  commandPools
  Vk.BUFFER_USAGE_INDEX_BUFFER_BIT
  1000
  (VectorS.fromList indices)

-- Create an observer for automatic buffer updates
bufferObserver <- newObserverCoherent
  "Scene Uniforms"
  Vk.BUFFER_USAGE_UNIFORM_BUFFER_BIT
  1
  (VectorS.singleton initialUniforms)

-- Observe and update buffer when source changes
observeCoherentResize_ dataSource bufferObserver

-- Peek/poke individual elements in coherent buffer
maybeValue <- peekCoherent 0 coherentBuffer
pokeCoherent coherentBuffer 0 newValue

```

--------------------------------

### Camera System: Spawn Perspective and Orthographic Projections

Source: https://context7.com/keid/engine/llms.txt

This snippet demonstrates how to spawn perspective and orthographic camera projections using the Engine.Camera module. It covers default perspective, custom perspective with specific parameters, and orthographic projections for 2D rendering. It also shows how to retrieve projection data and set up an orbital view.

```haskell
import Engine.Camera

-- Spawn a perspective projection (90 degree FOV by default)
projectionProcess <- spawnPerspective

-- Create custom perspective with specific parameters
customProjection <- spawnProjectionWith
  mkTransformPerspective
  ProjectionInput
    { projectionParams = pi / 3  -- 60 degree vertical FOV
    , projectionNear   = 0.1
    , projectionFar    = 1000.0
    }

-- Spawn orthographic projection for 2D rendering
orthoProjection <- spawnOrthoPixelsCentered

-- Get the projection transform
Projection{projectionTransform, projectionInverse} <- getOutputData projectionProcess

-- Create orbital view (camera orbiting a target)
let viewInput = initialOrbitalInput
      { orbitAzimuth  = pi / 4
      , orbitAscent   = pi / 6
      , orbitDistance = 10.0
      , orbitTarget   = vec3 0 0 0
      }

let view = mkViewOrbital_ viewInput
-- view.viewTransform    -- View matrix
-- view.viewPosition     -- Camera world position
-- view.viewDirection    -- Camera look direction

```

--------------------------------

### Integrate Dear ImGui with Vulkan (Haskell)

Source: https://context7.com/keid/engine/llms.txt

Integrates Dear ImGui for immediate-mode GUI rendering within a Vulkan render pass using the Render.ImGui module. Supports allocating ImGui resources, custom font loading, recording ImGui draw commands, and capturing input events.

```haskell
import Render.ImGui qualified as ImGui
import DearImGui qualified as DearImGui

-- Allocate ImGui in a stage's pipeline setup
allocateImGui
  :: HasRenderPass rp
  => SwapchainResources
  -> rp
  -> ResourceT (StageRIO st) ()
allocateImGui swapchain renderpass = do
  _key <- ImGui.allocate swapchain renderpass 0  -- subpass 0
  ImGui.allocateLoop True  -- install GLFW callbacks

-- Allocate with custom fonts
(key, fonts) <- ImGui.allocateWithFonts swapchain renderpass 0
  [ FontAtlas.FromTTF "fonts/Roboto.ttf" 16 Nothing Nothing
  , FontAtlas.FromTTF "fonts/Icons.ttf" 24 Nothing (Just iconRanges)
  ]

-- Record ImGui commands in render loop
recordCommands commandBuffer resources imageIndex = do
  -- Create draw data with UI logic
  (result, drawData) <- ImGui.mkDrawData do
    DearImGui.begin "Debug Window"
    DearImGui.text "Hello, Keid!"
    clicked <- DearImGui.button "Click Me"
    DearImGui.end
    pure clicked

  -- Draw ImGui
  ImGui.draw drawData commandBuffer

  -- Check if ImGui wants input
  ImGui.capturingKeyboard $ handleGameInput
  ImGui.capturingMouse $ handleMouseInput

-- Use layout system for full-screen UI
ImGui.rootLayout $ View.absolute 0 myWidget
```

--------------------------------

### Manage OpenAL Sound Devices (Haskell)

Source: https://context7.com/keid/engine/llms.txt

Provides audio device management and source control for the OpenAL sound system using the Engine.Sound.Device and Engine.Sound.Source modules. Supports allocating sound devices within a ResourceT monad or manual creation and destruction.

```haskell
import Engine.Sound.Device qualified as Sound.Device
import Engine.Sound.Source qualified as Sound.Source

-- Allocate sound device in ResourceT
(deviceKey, soundDevice) <- Sound.Device.allocate

-- Or create/destroy manually
soundDevice <- Sound.Device.create
-- ... use device ...
Sound.Device.destroy soundDevice
```

--------------------------------

### Graphics Pipeline: Create and Bind Graphics Pipelines

Source: https://context7.com/keid/engine/llms.txt

This section details the creation and usage of graphics pipelines in the engine, emphasizing type-safe descriptor set layouts and vertex formats. It shows how to define a pipeline type, configure its properties (like depth testing and culling), allocate it within a resource management context, and bind it during command recording for drawing.

```haskell
import Engine.Vulkan.Pipeline.Graphics qualified as Graphics
import Data.Tagged (Tagged(..))

-- Define pipeline type with descriptor sets, vertex, and instance formats
type MyPipeline = Graphics.Pipeline '[SceneDescriptors] MyVertex MyInstanceAttrs

-- Pipeline configuration
myPipelineConfig :: Graphics.Config '[SceneDescriptors] MyVertex MyInstanceAttrs ()
myPipelineConfig = Graphics.baseConfig
  {
    Graphics.cDescLayouts    = Tagged @'[SceneDescriptors] [sceneBindings]
  , Graphics.cStages         = Graphics.basicStages vertexSpirv fragmentSpirv
  , Graphics.cVertexInput    = Graphics.vertexInput @MyPipeline
  , Graphics.cBlend          = True
  , Graphics.cDepthTest      = True
  , Graphics.cDepthWrite     = True
  , Graphics.cDepthCompare   = Vk.COMPARE_OP_GREATER  -- Reverse-Z
  , Graphics.cTopology       = Vk.PRIMITIVE_TOPOLOGY_TRIANGLE_LIST
  , Graphics.cCull           = Vk.CULL_MODE_BACK_BIT
  }

-- Allocate pipeline in ResourceT
allocatePipeline
  :: (HasVulkan env, HasRenderPass rp)
  => Vk.SampleCountFlagBits
  -> Tagged SceneDescriptors DsLayoutBindings
  -> rp
  -> ResourceT (RIO env) MyPipeline
allocatePipeline msaa sceneBindings renderpass = do
  (_, pipeline) <- Graphics.allocate
    Nothing      -- dynamic viewport
    msaa
    myPipelineConfig
    renderpass
  pure pipeline

-- Bind pipeline during command recording
Graphics.bind commandBuffer myPipeline $ do
  -- Draw calls go here within the Bound monad
  Vk.cmdDrawIndexed commandBuffer indexCount 1 0 0 0

```

--------------------------------

### Load glTF and GLB Models (Haskell)

Source: https://context7.com/keid/engine/llms.txt

Loads glTF and GLB files using the Resource.Gltf.Load module. Supports loading mesh primitives, materials, and scene hierarchy. Includes functions for loading raw GLB data, standalone glTF files, and external URIs referenced by glTF.

```haskell
import Resource.Gltf.Load

-- Load mesh primitives from GLB file
(root, meshPrimitives) <- loadMeshPrimitives
  False  -- don't reverse indices
  True   -- add backsides for double-sided materials
  "models/scene.glb"

-- meshPrimitives :: Vector (Vector MeshPrimitive)
-- Each mesh contains multiple primitives with:
--   - Optional material reference
--   - Stuff { sPositions, sAttrs, sIndices }

-- Load raw GLB data and root
loadGlb "model.glb" >>= \case
  Right (bufferData, gltfRoot) -> do
    -- Process bufferData and gltfRoot
    pure ()
  Left err ->
    logError $ "Load failed: " <> fromString err

-- Load standalone glTF (references external buffers)
loadGltf "scene.gltf" >>= \case
  Right root -> processScene root
  Left err   -> handleError err

-- Load external URI referenced by glTF
loadUri "scene.gltf" "buffer0.bin" >>= \case
  Right bufferBytes -> useBuffer bufferBytes
  Left _            -> error "unreachable"
```

--------------------------------

### Stage Definition for Rendering Context in Haskell

Source: https://context7.com/keid/engine/llms.txt

Illustrates how to define a `Stage` in Haskell, representing a complete rendering context. This includes defining render passes, pipelines, resources, and state management for a specific part of the application's rendering.

```Haskell
import Engine.Types
import Engine.Vulkan.Types (RenderPass)
import Render.Pass (SimpleRenderPass, allocateSimple)
import qualified Vulkan.Core10 as Vk

data MyState = MyState
  { meshData :: SomeBuffers
  , camera   :: CameraData
  }

myStage :: Stage SimpleRenderPass MyPipelines MyResources MyState
myStage = Stage
  {
    sTitle = "Main Rendering Stage"

  , sAllocateRP = \swapchain ->
      allocateSimple swapchain

  , sAllocateP = \swapchain renderpass ->
      allocatePipelines swapchain renderpass

  , sInitialRS = do
      key <- allocate someResource
      state <- initializeState
      pure (key, state)

  , sInitialRR = \queues renderpass pipelines ->
      allocateRecycledResources queues

  , sBeforeLoop = do
      logInfo "Stage starting"
      pure ()

  , sUpdateBuffers = \state resources -> do
      updateSceneBuffers state resources

  , sRecordCommands = \commandBuffer resources imageIndex -> do
      recordRenderCommands commandBuffer resources

  , sAfterLoop = \_ ->
      logInfo "Stage finished"
  }
```

--------------------------------

### Reactive-Banana FRP Integration

Source: https://context7.com/keid/engine/llms.txt

Integrates the Worker system with reactive-banana for event-driven programming. It allows observing Worker.Var as events, creating debounced events, setting up timer events, and deriving behaviors. Events can be pushed to Worker variables, and debug output can be enabled.

```haskell
import Engine.ReactiveBanana
import Reactive.Banana qualified as RB
import Reactive.Banana.Frameworks qualified as RBF

-- Allocate a network that starts immediately
network <- allocateActuated $ \unlift started -> do
  -- 'started' fires once when network activates

  -- Observe Worker.Var as events
  screenEvents <- lift (observe screenSizeVar) >>= id

  -- Create debounced events (filters duplicates)
  debouncedScreen <- debounce initialSize screenEvents

  -- Set up timer events (60fps)
  timerMoment <- lift (timer 16666)
  ticks <- timerMoment

  -- Create derived behavior
  let screenBehavior = RB.stepper initialSize debouncedScreen

  -- Push events to Worker variables
  pushWorkerInput projectionVar $ 
    calculateProjection <$> screenBehavior <@> ticks

  -- Debug output
  reactimateDebugShow (unliftIO unlift) screenEvents

-- Allocate paused network (for manual control)
network <- allocatePaused $ \unlift -> do
  -- Network setup...
  pure ()

-- Create event from GLFW callback
keyEvents <- eventHandler $ \fire -> do
  registerKeyCallback $ \key action mods ->
    fire (key, action, mods)
  pure releaseKey

```

--------------------------------

### Load Textures from KTX2 Files (Haskell)

Source: https://context7.com/keid/engine/llms.txt

Loads various texture types (flat, cubemap, texture arrays) from KTX2 container files using the Resource.Texture.Ktx2 module. Supports different Vulkan formats and provides functions to convert loaded data to typed textures and access their properties like dimensions, format, mip levels, and layers.

```haskell
import Resource.Texture
import Resource.Texture.Ktx2 qualified as Ktx2

-- Load a flat texture from KTX2 file
texture <- Ktx2.load @Flat
  Vk.FORMAT_R8G8B8A8_SRGB
  commandPools
  "textures/diffuse.ktx2"

-- Load a cubemap (6 faces)
cubemap <- Ktx2.load @CubeMap
  Vk.FORMAT_R16G16B16A16_SFLOAT
  commandPools
  "textures/environment.ktx2"

-- Load texture array with specific layer count
textureArray <- Ktx2.load @(ArrayOf 16)
  Vk.FORMAT_R8G8B8A8_SRGB
  commandPools
  "textures/atlas.ktx2"

-- Convert AllocatedImage to typed Texture
typedTexture <- fromAllocatedImage @Flat allocatedImage

-- Get texture dimensions
let (width, height) = withSize2d (,) texture
let sizeVec = texture.size  -- Vec2

-- Access texture properties
let format = tFormat texture
let mipLevels = tMipLevels texture
let layers = tLayers texture
```

--------------------------------

### Reactive State Management with Workers in Haskell

Source: https://context7.com/keid/engine/llms.txt

Showcases the Worker module in Haskell for managing reactive state propagation using versioned variables and merge workers. This system automatically tracks changes and propagates updates through dependency chains, enabling efficient state management.

```Haskell
import Engine.Worker

-- Create a versioned variable
screenSize <- newVar (Vk.Extent2D 1920 1080)

-- Read current value
currentSize <- readVar screenSize

-- Push an update (increments version)
pushInput screenSize (\old -> old { Vk.width = 1280 })

-- Conditionally update
updateInput screenSize $ \size ->
  if Vk.width size > 800
    then Just size { Vk.width = 800 }
    else Nothing

-- Merge two inputs into derived output
projectionMerge <- spawnMerge2
  (\screenSize fov -> calculateProjection screenSize fov)
  screenSizeVar
  fovVar

-- Read merged output
projection <- getOutputData projectionMerge

-- Spawn a timer-driven worker
timerWorker <- spawnTimed
  True              -- start active
  (Left 16666)      -- 60fps in microseconds
  (\cfg -> pure (initialOutput, initialState))
  (\state cfg -> do
      newState <- stepSimulation state
      pure (Just newState, newState))
  ()

-- Create an observer for efficient change detection
observer <- newObserverIO initialValue
observeIO sourceVar observer $ \oldDerived newSource -> do
  -- Only called when source version changes
  pure $ deriveNewValue newSource
```

--------------------------------

### Geometry Primitives Generation

Source: https://context7.com/keid/engine/llms.txt

Provides basic shape generators for debugging and prototyping, including unit cube vertex positions, edge lines for wireframe rendering, colored wireframe cubes, and hex tile generation. It utilizes modules like Geometry.Cube and Geometry.Tile.Hex.

```haskell
import Geometry.Cube
import Geometry.Tile.Hex qualified as Hex
import Resource.Model (Vertex(..))

-- Unit cube vertex positions (centered at origin)
let cubePositions = positions  -- Vertices Vec3

-- Cube edge lines for wireframe rendering
let edgeVertices = edges  -- [Vec3]

-- Colored wireframe cube (red top, green bottom, blue sides)
let wireframeCube = bbWireColored  -- [Vertex Vec3.Packed Vec4]

-- Access individual cube vertices
let Vertices{vLTN, vLTF, vRBN, vRBF, ..} = positions
-- vLTN = Left-Top-Near corner, etc.

-- Hex tile generation
let hexVertices = Hex.vertices hexRadius
let hexIndices = Hex.indices

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.