Skip to main content
Version: 0.1.1

rayquiro.engine

rayquiro.engine is a powerful 3D/2D game-style native engine module built on top of the Raylib library. It provides high-performance rendering pipelines, entities, resource management, directional/ambient lighting, post-processing filters, input polling, and scene persistence workflows.

🚀 Installation​

Install globally on your machine:

rqio install rayquiro.engine

Or install locally in your project folder:

rqio install rayquiro.engine --local

🌐 Import​

import rayquiro.engine as engine;

(The alias raytolfas.engine is also accepted for backwards compatibility).

🛠️ Data Types & Conversions​

When passing data to rayquiro.engine APIs:

  • Vectors (3D): Passed as a 3-element numeric array [x, y, z]. E.g., [6.0, 4.0, 8.0].
  • Vectors (2D): Passed as a 2-element numeric array [x, y]. E.g., [1280.0, 720.0].
  • Colors: Passed as a 4-element RGBA numeric array [r, g, b, a] (each element 0-255). E.g., [255, 236, 206, 255].

🖥️ Window & Backend API​

engine.backend(name)​

Configures the graphics API.

  • name (string) — The backend engine name (e.g. "raylib" or "vulkan").

engine.backend_name()​

  • Returns: string — The active backend name.

engine.backend_info()​

  • Returns: table — A dictionary containing vendor, hardware, API version, and feature details.

engine.init(width, height, title) or engine.window(width, height, title)​

Creates the graphics window and initializes the rendering context.

  • width (number) — Window width.
  • height (number) — Window height.
  • title (string) — Display title.

engine.shutdown()​

Closes the engine window, unloads all cached assets, and cleans up memory.

engine.should_close()​

  • Returns: boolean — true if the window close button or ESC was pressed.

engine.vsync(enabled)​

  • enabled (boolean) — Enable or disable Vertical Synchronization.

engine.msaa(samples)​

  • samples (number) — Set multisample anti-aliasing sample count (e.g., 0, 2, 4, 8).

engine.target_fps(fps)​

  • fps (number) — Sets the target frame rate (e.g. 60, 144).

engine.frame_time()​

  • Returns: number — Time elapsed during the previous frame in seconds.

🎞️ Frame Lifecycle​

engine.begin() or engine.frame_begin()​

Clears the active frame buffer and begins recording render commands for the current frame.

engine.clear(color)​

Clears the active buffer with a background color.

  • color (RGBA array) — E.g., [10, 15, 24, 255].

engine.end() or engine.frame_end()​

Finalizes rendering commands, resolves shaders, applies postfx filters, and displays the frame.

📸 Camera API​

engine.camera(position, target, up, fov) or engine.set_camera(position, target, up, fov)​

Configures the default 3D rendering perspective camera.

  • position (3D vector) — Camera coordinates [x, y, z].
  • target (3D vector) — Point the camera looks at [x, y, z].
  • up (3D vector) — Up direction vector [x, y, z] (usually [0, 1, 0]).
  • fov (number) — Field of view angle (typically 60).

engine.camera_orbit(yaw, pitch, distance)​

Orbits the perspective camera around the target point.

  • yaw (number) — Rotation angle.
  • pitch (number) — Pitch/tilt angle.
  • distance (number) — Distance from target point.

engine.camera_fov(fov)​

  • fov (number) — Set or query the current camera field of view.

🗺️ Scene & Asset API​

engine.scene(name)​

Sets or creates an active scene space.

  • name (string) — Scene name.

engine.scene_clear()​

Removes all entities and resources from the active scene.

engine.scene_stats()​

  • Returns: table — Stats like total entities, mesh count, texture count, and active lighting.

engine.scene_draw()​

Renders all active scene entities automatically.

engine.scene_save(path)​

Saves the active scene metadata to a .scene file.

engine.scene_load(path)​

Loads a saved scene from a .scene file.

engine.scene_watch(path)​

Enables live file watching on the specified .scene file path. When modified, the engine automatically reloads it.

engine.scene_reload(path)​

Manually triggers a scene reload from the specified file.

📦 Mesh, Texture, & Material API​

engine.mesh(name, source, optionalData)​

Registers a mesh asset into the engine cache.

  • name (string) — Unique mesh name.
  • source (string) — Mesh type (e.g. "cube", "plane", "sphere") or path to a 3D model file (e.g. "assets/models/hero.obj").

engine.mesh_exists(name)​

  • Returns: boolean — true if the mesh is cached.

engine.texture(name, filePath)​

Registers a texture file into memory.

  • name (string) — Unique texture label.
  • filePath (string) — Path to the image file (e.g. "assets/textures/wood.png").

engine.texture_exists(name)​

  • Returns: boolean — true if the texture is loaded.

engine.material(name, albedo, roughness, metallic, emissive)​

Creates a custom PBR material.

  • name (string) — Material label.
  • albedo (RGBA array) — Base color.
  • roughness (number) — Roughness value (0.0 - 1.0).
  • metallic (number) — Metallic coefficient (0.0 - 1.0).
  • emissive (RGBA array) — Emissive light tint.

engine.material_exists(name)​

  • Returns: boolean — true if the material exists.

engine.material_texture(materialName, textureName)​

Binds a texture to a material slot.

  • materialName (string) — Target material.
  • textureName (string) — Cached texture name.

👾 Entity API​

engine.entity(name, kind, position, color)​

Spawns a new entity in the scene space.

  • name (string) — Unique entity name.
  • kind (string) — Mesh shape ("cube", "plane", "sphere").
  • position (3D vector) — Spawn coordinates [x, y, z].
  • color (RGBA array) — Base tint color.

engine.entity_remove(name)​

Removes the entity from the active scene.

engine.entity_exists(name)​

  • Returns: boolean — true if the entity is active.

engine.entity_set_position(name, position)​

  • position (3D vector) — [x, y, z].

engine.entity_get_position(name)​

  • Returns: 3D vector — The [x, y, z] coordinates.

engine.entity_set_size(name, size)​

  • size (3D vector) — Width, height, and depth dimensions.

engine.entity_set_scale(name, scale)​

  • scale (3D vector) — [x, y, z] scaling factors.

engine.entity_set_radius(name, radius)​

  • radius (number) — Radius value (sphere entities).

engine.entity_set_color(name, color)​

  • color (RGBA array) — [r, g, b, a].

engine.entity_set_visible(name, visible)​

  • visible (boolean) — Hide or show the entity.

engine.entity_mesh(entityName, meshName)​

Binds a custom mesh to the entity.

engine.entity_texture(entityName, textureName)​

Binds a texture to the entity.

engine.entity_material(entityName, materialName)​

Binds a material to the entity.

💡 Lighting API​

engine.light_ambient(color)​

Sets the ambient environment lighting color.

  • color (RGBA array) — E.g., [30, 30, 45, 255].

engine.light_directional(direction, color, intensity)​

Creates or updates the primary directional light source (like the Sun).

  • direction (3D vector) — Direction vector [x, y, z]. E.g., [0.5, -1.0, -0.5].
  • color (RGBA array) — Light color.
  • intensity (number) — Light strength (e.g. 1.0).

🎨 Post-Processing (FX) API​

Apply runtime rendering effects dynamically:

  • engine.exposure(value) — Sets HDR exposure level.
  • engine.vignette(value) — Sets vignette shadowing intensity.
  • engine.film_grain(value) — Adjusts visual noise/grain.
  • engine.saturation(value) — Adjusts color saturation factor.
  • engine.contrast(value) — Adjusts contrast multiplier.
  • engine.bloom(value) — Toggles bloom glow threshold.
  • engine.fog(color, near, far, density) — Sets scene distance fog.
  • engine.volumetric(value) — Configures volumetric light shafts.

⌨️ Input API​

engine.key_down(keyCode)​

  • Returns: boolean — true if the specified key is currently held down.

engine.key_pressed(keyCode)​

  • Returns: boolean — true if the key was clicked during this frame.

engine.mouse_down(buttonCode)​

  • Returns: boolean — true if the mouse button is pressed (0 for left, 1 for right).

engine.mouse_pos()​

  • Returns: 2D vector — Current screen coordinate array [x, y].

🖌️ Immediate Draw API​

Draw graphics directly to the screen (by-passing the entity manager). These must be called between engine.frame_begin() and engine.frame_end().

  • engine.draw_grid(slices, spacing) — Renders a grid pattern at the origin.
  • engine.draw_cube(position, size, color) — Draws a solid cube.
  • engine.draw_plane(position, size2d, color) — Draws a flat surface plane.
  • engine.draw_sphere(position, radius, color) — Draws a solid sphere.
  • engine.draw_text(text, x, y, fontSize, color) — Renders 2D screen text.
  • engine.draw_fps(x, y) — Draws the default frames-per-second indicator.