Cultiva Gameplay API

Cultiva Gameplay

Shared gameplay systems, machine APIs, energy networks, equipment frameworks, and gameplay-oriented utilities for the Cultiva ecosystem.

This module provides the gameplay foundation used by Cultiva technology, automation, progression, and equipment-based projects. It contains reusable APIs that allow addon developers to build machines, energy systems, inventories, logistics networks, recipes, and custom equipment without reinventing common mechanics.

---

Overview

Cultiva Gameplay is the primary gameplay framework layer of the Cultiva ecosystem.

The module focuses on reusable gameplay mechanics rather than backend infrastructure, providing a collection of APIs designed for technology mods, automation systems, progression mechanics, and equipment-driven content.

Package Root

net.xsoras.cultiva_gameplay

Main Module

cultiva-gameplay

Required Dependencies

cultiva-core
cultiva-runtime

---

Included Systems

Energy API

Provides a unified energy framework for Cultiva-based projects.

Main interfaces and implementations:

ICultivaEnergyStorage
ISidedCultivaEnergyStorage
CultivaEnergyStorage
TieredCultivaEnergyStorage

Features:

• Energy storage
• Energy transfer
• Sided interaction support
• Tiered capacity systems
• Machine integration

The API is intended to be lightweight and easy to integrate into custom blocks, machines, and automation systems.

---

Machine Framework

Provides reusable machine infrastructure.

Main classes:

ICultivaMachine
AbstractCultivaMachineBlockEntity

Features:

• Machine state management
• Processing logic foundations
• Energy integration
• Recipe processing support
• Block entity utilities

Developers can extend the abstract machine implementation to quickly create custom processing blocks.

---

Equipment System

Provides a modular equipment framework.

Main classes:

CultivaEquipmentCapability
CultivaEquipmentInventory
ICultivaEquipmentInventory
ICultivaEquipmentSlotType

Possible uses:

• Trinkets
• Artifacts
• Accessories
• Modular gear
• Custom equipment slots

The system supports custom slot definitions and expandable equipment architectures.

---

Inventory API

Provides inventory abstractions for gameplay systems.

Main interface:

ICultivaItemHandler

Features:

• Inventory interaction helpers
• Machine inventories
• Automation support
• Item transfer integration

---

Logistics API

Provides foundations for transportation and automation networks.

Main interface:

ICultivaLogisticsNode

Possible uses:

• Item networks
• Resource routing
• Automation chains
• Machine connectivity
• Transport systems

The API is intentionally generic so individual addons can define their own logistics behavior.

---

Recipe Framework

Provides reusable recipe abstractions.

Main interface:

ICultivaRecipe

Features:

• Machine recipes
• Processing recipes
• Custom crafting systems
• Data-driven integrations

---

Gameplay Events

Includes several gameplay-focused events.

Examples:

CultivaEnergyChangedEvent
CultivaMachineStateChangeEvent

Events allow addons to react to machine and energy changes without tightly coupling systems together.

---

World Data Attachments

Provides persistent world-level data storage.

Main class:

CultivaWorldDataAttachment

Possible applications:

• Global progression
• World statistics
• Shared machine networks
• Persistent automation data
• Dimension-wide systems

---

Optional Curios Support

Includes optional compatibility hooks for Curios-based equipment systems.

Features:

• Curios detection
• Equipment integration
• Optional runtime support
• Safe fallback behavior

---

Example Project Areas

Cultiva Gameplay is suitable for:

Technology Mods

Machines, generators, processors, factories, automation systems.

Equipment Expansions

Artifacts, relics, accessories, equipment progression systems.

Logistics Networks

Pipes, transport systems, resource routing, machine connectivity.

Progression Systems

Energy-based advancement, technology trees, machine tiers.

Automation Frameworks

Factories, processing chains, industrial gameplay loops.

---

Design Philosophy

Cultiva Gameplay follows several principles:

• Data-driven where possible
• Extensible by default
• Automation-friendly
• Technology-focused
• Minimal boilerplate
• Modular architecture
• Compatibility-oriented

The goal is to provide reusable gameplay foundations while allowing addon developers complete freedom over balance, progression, and content design.

---

When Should You Use It?

Use Cultiva Gameplay if your project requires:

✅ Energy systems

✅ Machines

✅ Automation

✅ Logistics networks

✅ Equipment frameworks

✅ Gameplay events

✅ Recipe processing systems

✅ Persistent gameplay data

You may not need this module if your project only requires:

✅ Backend utilities

✅ Networking

✅ Scheduling systems

✅ Core APIs

In those cases, Cultiva Runtime may be sufficient.

---

License & Customization

Cultiva Gameplay is designed as a reusable gameplay toolkit.

Developers may:

• Create custom machine implementations
• Extend energy systems
• Define new equipment slot types
• Build logistics frameworks
• Register custom recipes
• Implement unique progression mechanics

The framework provides the foundation while leaving gameplay design entirely in the hands of addon developers.