140 lines
4.8 KiB
Markdown
140 lines
4.8 KiB
Markdown
# CultUI
|
|
|
|
`CultUI` is a Unity runtime UI composition and inspector framework, packaged for UPM and developed alongside a demo project that showcases its components, layout system, and reflective inspector workflow.
|
|
|
|
This repository serves two purposes:
|
|
|
|
- the source of the `org.gamecult.ui` package
|
|
- the source of the `org.gamecult.caching.unity` CultCache editor package
|
|
- a Unity project for developing and demonstrating the package in a real scene
|
|
|
|
## Scope
|
|
|
|
CultUI is aimed at runtime, data-driven interface generation rather than hand-authoring every screen from scratch.
|
|
|
|
It is built for cases like:
|
|
|
|
- in-game settings menus
|
|
- debug and developer panels
|
|
- runtime inspectors for game objects and data models
|
|
- tools for exposing configurable values with minimal UI boilerplate
|
|
- reusable menu flows composed from prefabs and field handlers
|
|
|
|
## Features
|
|
|
|
- reflective runtime inspector generation for fields and properties
|
|
- prefab-driven resolver system for mapping value types to UI controls
|
|
- built-in field components for common input and display patterns
|
|
- foldouts and nested inspectors for structured data
|
|
- modal and color-picker style components
|
|
- reusable layout components for composing inspector rows and panels
|
|
- runtime menu composition for demos and application flows
|
|
- UPM-style package metadata and assembly definition for integration into Unity projects
|
|
|
|
## Package Layout
|
|
|
|
The package source lives under `Assets/UI`.
|
|
|
|
Key parts of the package include:
|
|
|
|
- `package.json`: package metadata for `org.gamecult.ui`
|
|
- `GameCult.Unity.UI.asmdef`: assembly definition for the runtime package
|
|
- `Generator.cs`: reflective inspector generation entry point
|
|
- `ReflectiveResolver.cs`: runtime resolver for prefab-backed field handlers and components
|
|
- `Components/`: built-in controls such as toggles, sliders, enum selectors, text input, buttons, labels, foldouts, and modal UI
|
|
- `Prefabs/`, `Resources/`, `Shaders/`: packaged assets used by the framework
|
|
|
|
## Demo Project
|
|
|
|
This repository also contains a Unity project used to develop and preview the package.
|
|
|
|
The demo project provides:
|
|
|
|
- a sample scene under `Assets/Scenes`
|
|
- package assets wired into a working Unity editor project
|
|
- demo menu flow showing how CultUI panels can be assembled at runtime
|
|
- CultCache Studio, a Unity editor window for opening and editing `.cc` files
|
|
- a place to iterate on prefabs, resources, and inspector behavior without needing a separate host project
|
|
|
|
## Installation
|
|
|
|
### Local Package Development
|
|
|
|
If you are working in this repository directly:
|
|
|
|
1. Open the project in Unity `6000.4.2f1`.
|
|
2. Let Unity import packages and regenerate project files.
|
|
3. Open the demo scene in `Assets/Scenes`.
|
|
|
|
### Installing As A UPM Package
|
|
|
|
To consume CultUI from another Unity project, reference the package by local path or Git URL in your project's `manifest.json`.
|
|
|
|
Example local reference:
|
|
|
|
```json
|
|
{
|
|
"dependencies": {
|
|
"org.gamecult.ui": "file:../path-to-CultUI/Assets/UI"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Usage
|
|
|
|
At a high level, CultUI works by combining:
|
|
|
|
- a `ReflectiveResolver` asset that knows which prefabs handle which value types
|
|
- reusable UI component prefabs
|
|
- a `Generator` or `GeneratorPanel` that inspects an object and emits UI rows at runtime
|
|
|
|
Typical flow:
|
|
|
|
1. Create or configure a `ReflectiveResolver`.
|
|
2. Assign field and component prefabs to the resolver.
|
|
3. Place a `Generator` or `GeneratorPanel` in your canvas hierarchy.
|
|
4. Call `Inspect(...)` on a target object or use the helper methods for explicit UI composition.
|
|
5. Refresh displayed values as your runtime state changes.
|
|
|
|
CultUI can be used both reflectively and imperatively:
|
|
|
|
- reflective mode generates inspector UI from object members
|
|
- imperative mode builds menus and panels directly through helper methods and component composition
|
|
|
|
## Included Controls
|
|
|
|
The package currently includes components for patterns such as:
|
|
|
|
- labels
|
|
- text buttons
|
|
- boolean toggles
|
|
- text input
|
|
- numeric sliders
|
|
- increment/decrement fields
|
|
- enum selection
|
|
- foldouts
|
|
- modal overlays
|
|
- color selection workflows
|
|
|
|
## Requirements
|
|
|
|
- Unity `6000.4.2f1` for this repository's demo project
|
|
- `uGUI`
|
|
- TextMeshPro
|
|
|
|
The development project also includes additional Unity packages and NuGet-managed dependencies used by the demo environment.
|
|
|
|
## Repository Structure
|
|
|
|
- `Assets/UI`: package source
|
|
- `Assets/Caching`: CultCache Unity editor package source
|
|
- `Assets/Scenes`: demo scene content
|
|
- `Assets/Prefabs`, `Assets/Resources`, `Assets/Scripts`: demo-project support assets and scripts
|
|
- `Packages`, `ProjectSettings`: Unity project configuration for package development and demonstration
|
|
|
|
## Development Notes
|
|
|
|
- the Unity project is the development host for the package
|
|
- generated `.csproj` and solution files are editor artifacts
|
|
- package-facing code should remain centered in `Assets/UI`
|
|
- demo-only code should stay separate from reusable package code
|