📦 Interns Module

Technical reference for the internals module of JarEngine.

🔹 Overview

Interns is a JarEngine module responsible for core engine infrastructure, internal abstractions, and foundational systems used across all engine layers.

It provides the classes and utilities required to:

Define base engine object behavior and identity management
Manage configuration and runtime settings
Handle internal resource containers (textures, fonts, animations)
Provide decorator-based metadata and reflection utilities
Expose final engine-level abstractions and typed stubs

🔹 Purpose

The Interns module aims to:

Centralize all low-level engine primitives
Standardize object lifecycle and debugging behavior
Provide reusable base classes for all engine components
Abstract engine configuration and resource handling
Support introspection and automatic documentation generation

It is not a gameplay module, but a core engine infrastructure layer.

🔹 Module Organization

sources/
└── interns/
    ├── base_classe.py
    ├── config.py
    ├── decorators.py
    ├── final_classes.py
    ├── high_classes.py
    ├── low_classes.py
    └── __init__.py

File	Description
`base_classe.py`	Base engine class providing identity, debugging, and serialization utilities
`config.py`	Engine configuration system wrapper over external config toolkit
`decorators.py`	Runtime documentation and introspection decorator system
`final_classes.py`	Final engine-level internal implementations (resources, window settings, components)
`high_classes.py`	High-level internal abstractions for entity and component systems
`low_classes.py`	Low-level rendering and core system primitives
`__init__.py`	Public module exports and external bindings

🔹 Responsibilities

Responsibility	Description
Base object identity	Provides unique identifiers and standard object representation
Engine configuration	Handles persistent configuration loading and creation
Resource management	Centralized access to textures, fonts, and animations
Debugging utilities	Recursive object inspection and formatted debug output
Documentation system	Automatic runtime metadata generation via decorators	+

🔹 Public Classes

Class	Description
`JEInternClassBase`	Base class for all engine objects with debug and serialization support
`JEInternConfig`	Configuration wrapper for engine settings
`documentation`	Decorator providing runtime introspection and documentation generation

Each class should have its own dedicated documentation page.

🔹 Dependencies

Depends On

pygame
jarbin_toolkit_time
jarbin_toolkit_console
jarbin_toolkit_action
jarbin_toolkit_error

🔹 Data Flow

External Input
   │
   ▼
internals module
   │
   ├── Base Classes (JEInternClassBase)
   ├── Config System (JEInternConfig)
   ├── Decorators
   ├── Resource/Final Classes
   │
   ▼
Engine Systems (High / Low / Final Layers)
   │
   ▼
Gameplay Layer

🔹 Usage

Basic Example

obj = JEInternClassBase()
cfg = get_config("engine")

Typical Workflow

@documentation
class MyClass(JEInternClassBase):
    pass

This workflow enables:

automatic introspection
structured debugging
standardized engine object behavior

🔹 Design Decisions

The module is designed around:

strict separation between internal engine layers and gameplay logic
centralized object identity system using UUID-based IDs
decorator-driven introspection instead of manual reflection tooling
minimal public API exposure to ensure controlled engine structure
explicit layering: low → high → final abstraction levels

🔹 Performance Notes

Uses lazy reflection for class inspection
Debug utilities may introduce overhead due to recursive traversal
Configuration system relies on external toolkit I/O operations
Containerized architecture favors modular access over raw performance

🔹 Limitations

Internal APIs are not stable for external usage
Debug and dump functions may be expensive on deep object graphs
Configuration path resolution depends on filesystem state
Some systems rely on external toolkits not bundled with core engine

🔹 Current State

⚠️ Current implementation status.

Implemented

Base class system with identity and debug tools
Configuration wrapper system
Decorator-based documentation system
Resource container abstractions (textures, fonts, animations)
Internal window settings abstraction

Planned

Extended introspection tooling
Improved configuration hot-reloading
Enhanced type safety across engine layers
More structured resource pipeline management

🔹 Notes

This module acts as the foundational layer of JarEngine. All higher-level systems depend on its structure, especially for identity management, debugging, and configuration consistency. Its design prioritizes clarity, traceability, and structured engine evolution over raw execution performance.

Module - Interns