Crate spottedcat

Expand description

§spottedcat

Spottedcat is a lightweight cross-platform 2D/3D game engine built with Rust and wgpu. It provides a simple API for rendering, input, audio, text, and scene management across desktop, web, iOS, and Android.

The engine uses a decoupled main loop with a fixed-step update (UPS) for logic and a variable refresh rate (FPS) for rendering, combined with built-in state interpolation for smooth visuals.

§Basic Example

use spottedcat::{Context, Spot, Image, DrawOption, Pt, WindowConfig};
use std::time::Duration;

struct MyApp {
    image: Image,
}

impl Spot for MyApp {
    fn initialize(ctx: &mut Context) -> Self {
        // Create an image from raw RGBA8 data
        let rgba = vec![255u8; 64 * 64 * 4]; // Red square
        let image = Image::new(ctx, Pt::from(64.0), Pt::from(64.0), &rgba)
            .expect("Failed to create image");
        Self { image }
    }

    fn update(&mut self, _ctx: &mut Context, _dt: Duration) {
        // Handle logic here
    }

    fn draw(&mut self, ctx: &mut Context, screen: Image) {
        let (w, h) = spottedcat::window_size(ctx);
         
        // Draw image at center
        let opts = DrawOption::default()
            .with_position([w / 2.0, h / 2.0])
            .with_scale([2.0, 2.0]);
             
        screen.draw(ctx, &self.image, opts);
    }
}

fn main() {
    spottedcat::run::<MyApp>(WindowConfig {
        title: "SpottedCat Example".to_string(),
        ..Default::default()
    });
}

Re-exports§

pub use image::Bounds;
pub use image::Image;
pub use model::Model;
pub use text::Text;
pub use utils::image::AsyncImageLoader;
pub use utils::image::LoadingImage;
pub use utils::image::load_image_async;

Modules§

image
math: Centralized 3D math utilities using ultraviolet internally. All public APIs use standard Rust arrays to hide implementation details.
model
text
utils

Structs§

Context: Drawing context for managing render commands.
DrawOption: Unified options for drawing images and text.
DrawOption3D: Unified options for drawing 3D models.
FogBackgroundSettings: Style controls for the fullscreen fog background pass.
FogSamplingSettings: Quality / cost controls for the fullscreen fog pass.
FogSettings: Engine-level fog configuration.
GamepadId: Stable identifier assigned to a connected gamepad.
GamepadInfo: Basic information about a gamepad known to the input system.
ImageShaderBindings: Per-draw image shader bindings.
ImageShaderDesc: High-level description for registering a custom image shader.
ImageShaderTemplate: A builder for creating data-driven image shaders with automatic boilerplate injection.
InputManager: Manages the state of all input devices (keyboard, mouse, touch, sensors).
ModelShaderTemplate
OneShotSplash: A reusable startup splash scene with the built-in Spottedcat branding.
Pt: A single dimension unit for logical screen positions and sizes.
ShaderOpts: Uniform options passed to the fragment shader during rendering.
SoundOptions: Configuration options for playing a sound.
Texture: Handle to a texture resource.
TouchInfo: Information about a single active touch point.
WindowConfig: Configuration for the application window.

Enums§

GamepadAxis: Logical gamepad axes exposed by spottedcat.
GamepadButton: Logical gamepad buttons exposed by spottedcat.
ImageRepeat: Controls how an image is sampled when the drawn quad is larger than one tile.
ImageShaderBlendMode: Supported high-level blend modes for image shaders.
ImageShaderInput: Optional per-draw bindings for custom image shaders.
Key: Represents a physical key on a keyboard.
MouseButton: Represents a button on a mouse or similar pointing device.
PlatformEvent: Events received from the native platform (e.g. Android JNI or iOS ObjC).
TouchPhase: Represents the current state of a touch interaction.

Traits§

Drawable: Trait for objects that can be drawn into an Image.
Spot: The core trait for defining application logic and rendering.

Functions§

accelerometer: Returns the current accelerometer readings [x, y, z] if available.
camera_position: Returns current camera eye position.
clear_fog: Resets global fog to the default disabled state.
cursor_position: Returns the current hardware cursor position in logical coordinates.
delta_time: Returns the time elapsed since the last frame.
dt: Returns the time elapsed since the last frame in seconds.
fade_in_sound: Initiates a fade-in for a playing sound.
fade_out_sound: Initiates a fade-out for a playing sound.
gamepad_axis: Returns the current value of a gamepad axis, or 0.0 if unavailable.
gamepad_button_down: Returns true if the specified gamepad button is currently held down.
gamepad_button_pressed: Returns true if the specified gamepad button was just pressed this frame.
gamepad_button_released: Returns true if the specified gamepad button was just released this frame.
gamepad_connected: Returns true if the gamepad is currently connected.
gamepads: Returns basic information for every gamepad known to the input system.
get_input: Compatibility alias for text_input.
get_registered_font: Returns a copy of the raw bytes for a registered font.
get_resource: Returns a resource of type T from the context, if it exists.
gyroscope: Returns the current gyroscope readings [x, y, z] if available.
image_shader_template: Returns a full WGSL image shader template that matches Spot’s current image pipeline contract.
ime_preedit: Returns the current IME pre-edit string (uncommitted text).
insert_resource: Inserts or replaces a resource of type T in the context.
is_background_transparent: Returns whether the current window background is transparent.
is_sound_playing: Returns true if the sound associated with the play ID is still active.
key_down: Returns true if the specified key is currently held down.
key_pressed: Returns true if the specified key was just pressed this frame.
key_released: Returns true if the specified key was just released this frame.
load_asset: Loads an asset from disk or from the platform-specific bundle.
magnetometer: Returns the current magnetometer readings [x, y, z] if available.
model_shader_template: Returns a full WGSL model shader template that matches Spot’s current 3D pipeline contract.
mouse_button_down: Returns true if the specified mouse button is currently held down.
mouse_button_pressed: Returns true if the specified mouse button was just pressed this frame.
mouse_button_pressed_position: Returns the cursor position if the mouse button was just pressed this frame.
mouse_button_released: Returns true if the specified mouse button was just released this frame.
mouse_down: Returns true if the specified mouse button is currently held down.
mouse_pos: Returns the current mouse position in logical coordinates.
mouse_pressed: Returns true if the specified mouse button was just pressed this frame.
mouse_released: Returns true if the specified mouse button was just released this frame.
pause_sound: Pauses a currently playing sound by its play ID.
play_sine: A debug function to play a simple sine wave at the specified frequency.
play_sound: Plays a registered sound with the specified options.
play_sound_simple: A convenience function to play a registered sound with default options.
poll_platform_events: Returns a list of raw platform events received this frame.
pt: Creates a logical point value (Pt) from a scalar.
push_platform_event: Pushes a custom platform event into the event queue.
quit: Signals the engine to quit the application.
quit_ctx: Quit helper that keeps the ctx-first API shape.
rebuild_assets: Forces pending asset rebuild/re-upload to GPU to run immediately.
register_font: Registers a TTF/OTF font for text rendering and returns a unique font ID.
register_image_shader_desc: Registers a custom image shader using the descriptor API.
register_image_shader_template: Registers an image shader generated from the template API.
register_model_shader: Registers a full WGSL 3D model shader and returns its shader id.
register_model_shader_template: Registers a model shader generated from the template API.
register_sound: Registers a sound from raw bytes (supported formats depend on backend).
resume_sound: Resumes a paused sound by its play ID.
rotation: Returns the current device rotation as a quaternion [x, y, z, w].
run: Starts the application with the specified scene type T and configuration.
scale_factor: Returns the window’s scale factor (DPI).
scroll_delta: Returns the current frame’s scroll wheel delta.
set_ambient: Sets ambient light color.
set_ambient_light: Sets the ambient light color for the active 3D scene.
set_background_transparent: Sets whether the current window background should be transparent.
set_camera: Sets camera eye, target and up vectors in one call.
set_camera_fovy: Sets camera vertical field of view in degrees.
set_camera_pos: Sets camera eye position.
set_camera_target: Sets camera target vector.
set_camera_up: Sets camera up vector.
set_cursor_visible: Requests cursor visibility update.
set_fog: Sets global fog settings.
set_fullscreen: Requests fullscreen toggle.
set_light: Sets a PBR light (up to 4 lights).
set_sound_volume: Sets the volume of a playing sound directly.
set_text_input_enabled: Enables or disables text input (IME) for the window.
set_window_size: Sets the window’s logical size.
set_window_title: Requests a window title update.
step_count: Compatibility alias for today_step_count.
step_detected: Returns true if a single step was detected this frame.
stop_all_sounds: Stops all currently playing sounds.
stop_sound: Stops a playing sound immediately by its play ID.
switch_scene: Switches to a new scene of type T.
switch_scene_ctx: Scene switch helper that keeps the ctx-first API shape.
switch_scene_with: Switches to a new scene of type T and passes a payload.
switch_scene_with_ctx: Scene switch with payload helper that keeps the ctx-first API shape.
take_resource: Removes and returns a resource of type T from the context, if it exists.
text_input: Returns the accumulated text input string for the current frame.
text_input_enabled: Returns true if text input (IME) is currently enabled.
today_step_count: Returns the current day’s step count when the platform provides it.
total_elapsed: Returns total elapsed time since engine start.
touch_down: Returns true if any touch point is currently active.
touches: Returns a slice of active touch points.
unregister_font: Unregisters a font and clears any cached GPU state for it.
unregister_sound: Unregisters a sound and frees its resources.
vh: Returns a percentage of the window height as Pt.
vw: Returns a percentage of the window width as Pt.
window_size: Returns the window’s logical size as a tuple of (width, height).
yesterday_step_count: Returns the step count for the previous local day.

Type Aliases§

ImageShaderTemplateBuilder
ModelShaderTemplateBuilder

Crate spottedcat

Crate spottedcat Copy item path

§spottedcat

§Basic Example

Re-exports§

Modules§

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Crate spottedcat