Enum GoudError 

pub enum GoudError {
    NotInitialized,
    AlreadyInitialized,
    InvalidContext,
    ContextDestroyed,
    InitializationFailed(String),
    ResourceNotFound(String),
    ResourceLoadFailed(String),
    ResourceInvalidFormat(String),
    ResourceAlreadyExists(String),
    InvalidHandle,
    HandleExpired,
    HandleTypeMismatch,
    ShaderCompilationFailed(String),
    ShaderLinkFailed(String),
    TextureCreationFailed(String),
    BufferCreationFailed(String),
    RenderTargetFailed(String),
    BackendNotSupported(String),
    DrawCallFailed(String),
    EntityNotFound,
    EntityAlreadyExists,
    ComponentNotFound,
    ComponentAlreadyExists,
    QueryFailed(String),
    WindowCreationFailed(String),
    AudioInitFailed(String),
    PhysicsInitFailed(String),
    PlatformError(String),
    InternalError(String),
    NotImplemented(String),
    InvalidState(String),
}

The main error type for GoudEngine.

This enum represents all possible errors that can occur within the engine. Each variant maps to a specific FFI-compatible error code, enabling consistent error handling across Rust and all language bindings.

Error Categories

Errors are organized into categories:

• Context: Engine initialization and context management (codes 1-99)
• More categories will be added in subsequent steps

FFI Compatibility

Use GoudError::error_code() to get the FFI-compatible error code for any error. This code can be safely passed across the FFI boundary.

Example

use goud_engine::core::error::{GoudError, ERR_NOT_INITIALIZED};

let error = GoudError::NotInitialized;
assert_eq!(error.error_code(), ERR_NOT_INITIALIZED);

Variants

NotInitialized

Engine has not been initialized.

This error occurs when attempting to use engine functionality before calling the initialization function.

AlreadyInitialized

Engine has already been initialized.

This error occurs when attempting to initialize the engine more than once. The engine must be shut down before re-initialization.

InvalidContext

Invalid engine context.

The provided engine context handle is invalid or corrupted.

ContextDestroyed

Engine context has been destroyed.

The engine context was previously valid but has since been destroyed. Operations cannot be performed on a destroyed context.

InitializationFailed(String)

Engine initialization failed with a specific reason.

Contains a message describing why initialization failed. Common causes include missing dependencies, invalid configuration, or platform-specific issues.

ResourceNotFound(String)

Requested resource was not found.

This error occurs when attempting to access a resource (texture, shader, audio file, etc.) that does not exist at the specified path or identifier. The string contains the resource path or identifier that was not found.

ResourceLoadFailed(String)

Failed to load resource from source.

This error occurs when a resource exists but could not be loaded due to I/O errors, permission issues, or other loading failures. The string contains details about the loading failure.

ResourceInvalidFormat(String)

Resource format is invalid or unsupported.

This error occurs when a resource file exists and was read successfully, but the format is invalid, corrupted, or not supported by the engine. The string contains details about the format issue.

ResourceAlreadyExists(String)

Resource with this identifier already exists.

This error occurs when attempting to create or register a resource with an identifier that is already in use. The string contains the conflicting resource identifier.

InvalidHandle

Handle is invalid (null or malformed).

This error occurs when an operation is performed with a handle that was never valid (null, zero, or otherwise malformed).

HandleExpired

Handle refers to a resource that has been deallocated.

This error occurs when using a handle that was previously valid but the underlying resource has been freed. This is a use-after-free attempt that was safely caught by the generational handle system.

HandleTypeMismatch

Handle type does not match expected resource type.

This error occurs when a handle is passed to a function expecting a different resource type (e.g., passing a texture handle to a shader function).

ShaderCompilationFailed(String)

Shader compilation failed.

This error occurs when a vertex, fragment, or compute shader fails to compile. The string contains the shader compiler error message, which typically includes line numbers and error descriptions from the GPU driver.

ShaderLinkFailed(String)

Shader program linking failed.

This error occurs when compiled shaders fail to link into a program. Common causes include mismatched inputs/outputs between shader stages, missing uniforms, or exceeding GPU resource limits. The string contains the linker error message.

TextureCreationFailed(String)

Texture creation failed.

This error occurs when the GPU fails to allocate or create a texture. Common causes include insufficient GPU memory, unsupported texture format, or dimensions exceeding GPU limits. The string contains details about the failure.

BufferCreationFailed(String)

Buffer creation failed.

This error occurs when the GPU fails to allocate a buffer (vertex, index, uniform, or storage buffer). Common causes include insufficient GPU memory or exceeding buffer size limits. The string contains details about the failure.

RenderTargetFailed(String)

Render target creation failed.

This error occurs when creating a framebuffer or render target fails. Common causes include unsupported attachment formats, mismatched attachment dimensions, or exceeding attachment limits. The string contains details about the failure.

BackendNotSupported(String)

Graphics backend not supported on this platform.

This error occurs when the requested graphics API (OpenGL, Vulkan, Metal, etc.) is not available on the current platform or the installed GPU driver does not meet minimum version requirements. The string contains the requested backend and available alternatives.

DrawCallFailed(String)

Draw call failed.

This error occurs when a draw call fails during rendering. This is typically a serious error indicating GPU state corruption, invalid buffer bindings, or driver issues. The string contains details about the failed draw call.

EntityNotFound

Entity was not found.

This error occurs when attempting to access an entity that does not exist in the world, either because it was never created or has been despawned.

EntityAlreadyExists

Entity already exists.

This error occurs when attempting to create an entity with an ID that is already in use. This typically indicates a logic error in entity management.

ComponentNotFound

Component was not found on entity.

This error occurs when querying or accessing a component type that the specified entity does not have attached.

ComponentAlreadyExists

Component already exists on entity.

This error occurs when attempting to add a component type that the entity already has. Use replace or update methods instead.

QueryFailed(String)

Query execution failed.

This error occurs when an ECS query fails to execute. Common causes include conflicting access patterns (mutable + immutable on same component) or invalid query parameters. The string contains details about the query failure.

WindowCreationFailed(String)

Window creation failed.

This error occurs when the platform window system fails to create a window. Common causes include missing display server, invalid window parameters, or resource exhaustion. The string contains details about the failure.

AudioInitFailed(String)

Audio system initialization failed.

This error occurs when the audio subsystem fails to initialize. Common causes include missing audio devices, driver issues, or unsupported audio formats. The string contains details about the failure.

PhysicsInitFailed(String)

Physics system initialization failed.

This error occurs when the physics engine fails to initialize. Common causes include invalid physics configuration or incompatible settings. The string contains details about the failure.

PlatformError(String)

Generic platform error.

This error occurs for platform-specific failures that don’t fit into other categories. The string contains platform-specific error details.

InternalError(String)

Internal engine error.

This error indicates an unexpected internal state or failure within the engine. These errors typically indicate bugs in the engine itself and should be reported. The string contains details about the internal failure.

NotImplemented(String)

Feature not yet implemented.

This error occurs when attempting to use a feature that has not been implemented yet. This is primarily used during development to mark incomplete functionality. The string contains details about the unimplemented feature.

InvalidState(String)

Invalid engine state.

This error occurs when the engine is in an invalid or unexpected state. This typically indicates a bug in state management or an invalid sequence of operations. The string contains details about the invalid state.

Implementations

impl GoudError

pub const fn error_code(&self) -> i32

Returns the FFI-compatible error code for this error.

This method maps each error variant to its corresponding error code constant, which can be safely passed across the FFI boundary to C#, Python, or other language bindings.

Example

use goud_engine::core::error::{GoudError, ERR_NOT_INITIALIZED, ERR_INITIALIZATION_FAILED};

assert_eq!(GoudError::NotInitialized.error_code(), ERR_NOT_INITIALIZED);
assert_eq!(
    GoudError::InitializationFailed("GPU not found".to_string()).error_code(),
    ERR_INITIALIZATION_FAILED
);

pub const fn category(&self) -> &'static str

Returns the error category as a static string.

This is a convenience method that returns the category name for this error.

Example

use goud_engine::core::error::GoudError;

assert_eq!(GoudError::NotInitialized.category(), "Context");

pub fn message(&self) -> &str

Returns the error message for errors that contain one, or a default description.

For errors with associated string messages, this returns the message. For errors without messages, this returns a default description.

Example

use goud_engine::core::error::GoudError;

let error = GoudError::InitializationFailed("GPU not found".to_string());
assert_eq!(error.message(), "GPU not found");

let error = GoudError::NotInitialized;
assert_eq!(error.message(), "Engine has not been initialized");

Trait Implementations

impl Clone for GoudError

fn clone(&self) -> GoudError

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for GoudError

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Display for GoudError

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the error for user-friendly display.

Format: "[GOUD-{code}] {category}: {message}"

Example

use goud_engine::core::error::GoudError;

let error = GoudError::NotInitialized;
let display = format!("{}", error);
assert!(display.contains("[GOUD-1]"));
assert!(display.contains("Context"));

impl Error for GoudError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the source of this error, if any.

Currently, GoudError does not wrap other errors, so this always returns None. Future versions may add error chaining for wrapped errors.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<&str> for GoudError

fn from(msg: &str) -> GoudError

Converts a string slice into a GoudError::InternalError.

This is a convenience conversion for creating internal errors from string literals.

Example

use goud_engine::core::error::GoudError;

let error: GoudError = "something went wrong".into();
assert!(matches!(error, GoudError::InternalError(_)));

impl From<Error> for GoudError

fn from(error: Error) -> GoudError

Converts an I/O error into a GoudError.

The I/O error is mapped to an appropriate GoudError variant based on its kind:

• NotFound -> ResourceNotFound
• PermissionDenied -> ResourceLoadFailed
• Other -> ResourceLoadFailed with the error message

Example

use goud_engine::core::error::GoudError;
use std::io;

let io_error = io::Error::new(io::ErrorKind::NotFound, "file not found");
let goud_error: GoudError = io_error.into();
assert!(matches!(goud_error, GoudError::ResourceNotFound(_)));

impl From<String> for GoudError

fn from(msg: String) -> GoudError

Converts a string into a GoudError::InternalError.

This is a convenience conversion for creating internal errors from strings. Use more specific error variants when the error category is known.

Example

use goud_engine::core::error::GoudError;

let error: GoudError = "something went wrong".to_string().into();
assert!(matches!(error, GoudError::InternalError(_)));

impl PartialEq for GoudError

fn eq(&self, other: &GoudError) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for GoudError

impl StructuralPartialEq for GoudError