Contributing Guidelines - Orbis Galactic

Getting Started

Welcome to the Orbis Galactic project! This guide will help you understand how to contribute to this Star Wars mod for Hytale.

Project Information

Repository: https://github.com/Tasty-Syntax/Orbis-Galactic
Version: 1.4.0
Maintained by: TastySyntax team (Cerzix, Viluron, Nelayx, Holag)

Before contributing, familiarize yourself with the Project Structure to understand how the mod is organized.

How to Contribute

Types of Contributions

We welcome various types of contributions:

New Content
- Weapons (lightsabers, blasters, melee weapons)
- Blocks and decorations
- NPCs and creatures
- Planets and environments
- Vehicles and speeders
Assets
- 3D models (Blockbench)
- Textures and skins
- Sound effects and music
- Animations
- Particle effects
Improvements
- Bug fixes
- Performance optimizations
- Balance adjustments
- Documentation updates
Localization
- Translations to other languages
- Text improvements

Development Environment Setup

Required Tools

Hytale Modding Tools (when available)
Blockbench - For 3D modeling
Audio Editor - For sound creation (Audacity recommended)
Image Editor - For texture creation (GIMP, Photoshop, etc.)
Git - For version control
Text Editor/IDE - For JSON editing (VS Code recommended)

Repository Setup

# Clone the repository
git clone https://github.com/Tasty-Syntax/Orbis-Galactic.git
cd Orbis-Galactic

# Create a new branch for your contribution
git checkout -b feature/your-feature-name

Contribution Workflow

1. Planning Your Contribution

Before starting work:

Check existing issues and pull requests to avoid duplicate work
Open an issue to discuss major changes or new features
Review the project structure to understand where your files should go
Gather reference materials (Star Wars canon sources)

2. Creating Content

Follow these best practices when creating new content:

Naming Conventions

All mod-specific content should use the OrbisGalactic_ prefix to avoid conflicts with base game content and other mods.

Files and IDs:

Use descriptive, clear names
Follow existing naming patterns in the same category
Use underscores to separate words: OrbisGalactic_Item_Name
Include variant descriptors: _Blue, _Red, _Variant1

Example naming patterns:

OrbisGalactic_SFX_Lightsaber_Attack_Blue_Local
Bench_Laser_Weapon_Crafter
Blaster_DC15A
OrbisGalactic_Kyber_Crystal_Clear

File Organization

Models and Textures:

# Weapon example
Common/Items/Weapons/Blaster_NewWeapon/
├── Blaster_NewWeapon_Model.blockymodel
└── Blaster_NewWeapon_Texture.png

# Also store in Resources for organization
Common/Resources/WeaponModels/Blaster_NewWeapon_Model.blockymodel
Common/Resources/WeaponTextures/Blaster_NewWeapon_Texture.png

Sounds:

# Audio file
Common/Sounds/Weapons/NewWeapon/NewWeapon_Fire.ogg

# Sound event configuration
Server/Audio/SoundEvents/SFX/NewWeapon/OrbisGalactic_SFX_NewWeapon_Fire.json

Configuration:

# Item definition
Server/Item/Items/Orbis Galactic/NewItem.json

# Translations
Server/Languages/en-US/items.json

3. Creating Models

Blockbench Workflow

Create your model in Blockbench
- Follow Star Wars aesthetic and proportions
- Keep polygon count reasonable for performance
- Use appropriate pivot points for animations
Save source file
- Location: Common/Resources/Blockbench Files/
- Naming: [ItemName].bbmodel
Export for Hytale
- Export as .blockymodel
- Location: Common/Resources/[Type]Models/
- Test in-game to verify appearance
Create textures
- Resolution: Use appropriate size (typically 16x16, 32x32, or 64x64)
- Format: PNG with transparency support
- Location: Common/Resources/[Type]Textures/

Keep source .bbmodel files so other contributors can modify models if needed. Always export to both the item directory and Resources directory.

4. Adding Sounds

Audio Requirements

Format: OGG Vorbis
Sample Rate: 44.1 kHz recommended
Bit Depth: 16-bit minimum
Channels: Mono for positional sounds, Stereo for music

Audio Workflow

Prepare audio file

# Use the normalization script for consistent volume
scripts/normalize_audio.sh your_audio.wav

Place audio file
- Location: Common/Sounds/[Category]/[Subcategory]/
- Example: Common/Sounds/Weapons/Lightsaber/Blue/Lightsaber_Ignite_Blue_Local.ogg

Create sound event

Location: Server/Audio/SoundEvents/[Category]/
Reference the audio file path Example JSON structure:

{
  "Volume": 0,
  "PreventSoundInterruption": false,
  "AudioCategory": "AudioCat_Sword",
  "Layers": [
    {
      "Files": [
        "Sounds/Weapons/NewWeapon/NewWeapon_Fire.ogg"
      ],
      "Volume": 0,
      "StartDelay": 0
    }
  ],
  "Parent": "SFX_Attn_Moderate"
}

Link to item/block
- Reference the sound event ID in your item JSON
- Test in-game to verify playback

5. Creating Item Definitions

Item JSON Structure

Item definitions go in Server/Item/Items/[Category]/[ItemName].json Key sections to include: Translation Properties:

"TranslationProperties": {
  "Name": "server.items.Category_ItemName.name",
  "Description": "server.items.Category_ItemName.description"
}

Visual Properties:

"Icon": "Icons/ItemsGenerated/ItemName.png",
"IconProperties": {
  "Scale": 0.4,
  "Rotation": [21, 32, 19],
  "Translation": [16, -9]
}

Categories:

"Categories": [
  "OrbisGalactic.Weapons",
  "OrbisGalactic.Lightsabers"
]

Crafting Recipe:

"Recipe": {
  "TimeSeconds": 4,
  "Input": [
    {
      "ItemId": "OrbisGalactic_Kyber_Crystal_Clear",
      "Quantity": 1
    }
  ],
  "BenchRequirement": [
    {
      "Type": "Crafting",
      "Categories": ["Lightsaber_Crafting"],
      "Id": "Bench_Laser_Weapon_Crafter",
      "RequiredTierLevel": 1
    }
  ]
}

See Server/Item/Items/Benches/Bench_Laser_Weapon_Crafter.json for a complete, real-world example of an item definition.

Block Properties (for placeable items):

"BlockType": {
  "Material": "Solid",
  "DrawType": "Model",
  "Opacity": "Transparent",
  "CustomModel": "Resources/PropModels/ModelName.blockymodel",
  "CustomModelTexture": [
    {
      "Texture": "Resources/PropTextures/TextureName.png",
      "Weight": 1
    }
  ],
  "VariantRotation": "NESW",
  "BlockSoundSetId": "Stone"
}

6. Adding Translations

All text content must be localized in Server/Languages/en-US/

{
  "server.items.Weapon_Lightsaber_Blue.name": "Blue Lightsaber",
  "server.items.Weapon_Lightsaber_Blue.description": "An elegant weapon for a more civilized age."
}

For new languages, create a new directory (e.g., Server/Languages/es-ES/) following the same structure.

7. Testing Your Changes

Always test your contributions in-game before submitting a pull request.

Testing checklist:

Models display correctly in-game
Textures load without errors
Sounds play at appropriate volume and timing
Items can be crafted with correct recipes
Blocks can be placed and broken
Translations display correctly
No console errors or warnings
Performance is acceptable
Interactions work as intended

8. Submitting Your Contribution

Commit Guidelines

Write clear commit messages:

# Good commit messages
git commit -m "Add blue lightsaber variant with custom sound effects"
git commit -m "Fix blaster projectile speed and damage values"
git commit -m "Update Tatooine prefab with additional details"

# Bad commit messages
git commit -m "update"
git commit -m "fixes"
git commit -m "WIP"

Commit message format:

[Type]: Brief description

Detailed explanation if needed:
- What was changed
- Why it was changed
- Any breaking changes or considerations

Types:

Add: New features or content
Fix: Bug fixes
Update: Improvements to existing content
Remove: Deletion of content
Docs: Documentation changes
Refactor: Code restructuring

Pull Request Process

Prepare your branch

# Make sure you're up to date
git fetch origin
git rebase origin/main

# Push your changes
git push origin feature/your-feature-name

Create pull request
- Go to GitHub repository
- Click “New Pull Request”
- Select your branch
- Fill out the PR template
PR Description should include:
- What: What does this PR add/change/fix?
- Why: Why is this change needed?
- How: How does it work?
- Testing: What testing was done?
- Screenshots/Videos: Visual changes should include media
- References: Link to related issues
Address review feedback
- Respond to comments
- Make requested changes
- Push updates to your branch
- Re-request review when ready

Content Guidelines

Star Wars Canon Adherence

While we aim for authenticity, gameplay and fun take priority over strict canon adherence. Creative interpretations are welcome!

Guidelines:

Research reference materials from Star Wars media
Maintain consistent visual style with existing content
Respect the lore and setting
Balance game mechanics with thematic authenticity

Balance Considerations

Weapons:

Lightsabers should feel powerful but not overpowered
Blasters should have distinct roles (sniper, assault, pistol)
Consider range, damage, fire rate, and resource costs

Crafting:

Recipes should require appropriate materials
Progression should feel rewarding
Rare items should have rare ingredients
Consider bench tier requirements

Blocks and Decorations:

Should fit the Star Wars aesthetic
Consider practical building use cases
Provide variety within categories

Quality Standards

Models:

Clean topology
Appropriate detail level for game performance
Proper UV mapping
Consistent scale with existing items

Textures:

Consistent art style
Appropriate resolution
Use of transparency where needed
Optimized file size

Sounds:

Clear, high-quality audio
Appropriate volume levels
No clipping or distortion
Proper format and sample rate

Code/JSON:

Valid JSON syntax
Consistent formatting (2-space indentation)
Commented where necessary
Follow existing patterns

Common Tasks

Adding a New Lightsaber

Create the model and texture
- Blockbench file: Common/Resources/Blockbench Files/Lightsaber_[Name].bbmodel
- Export model: Common/Resources/WeaponModels/Lightsaber_[Name].blockymodel
- Create texture: Common/Resources/WeaponTextures/Lightsaber_[Name].png
Add sounds
- Place audio files in: Common/Sounds/Weapons/Lightsaber/[Color]/
- Create sound events for: equip, unequip, attack, charged attack, hum
- Location: Server/Audio/SoundEvents/SFX/Lightsabers/[Color]/
Create item definition
- File: Server/Item/Items/Orbis Galactic/Lightsaber_[Name].json
- Include weapon stats, crafting recipe, sound references
- Set appropriate bench requirement (Bench_Laser_Weapon_Crafter)
Add translations
- In Server/Languages/en-US/items.json
- Include name and description
Create animation (if custom)
- Animation file: Common/Resources/Animations/Lightsaber_[Name]_Animation.json
- Reference in item definition

Adding a New Block

Create model and texture
- Model: Common/Resources/BlockModels/[BlockName].blockymodel
- Texture: Common/Resources/BlockTextures/[BlockName].png
Define block item
- File: Server/Item/Items/[Category]/[BlockName].json
- Include BlockType properties, gathering info, support requirements
Add block sounds (if custom)
- Place audio: Common/Sounds/Blocks/[BlockName]/
- Create sound event: Server/Audio/SoundEvents/BlockSounds/
- Or use existing: "BlockSoundSetId": "Stone"
Create icon
- Generate or create: Common/Icons/ItemsGenerated/[BlockName].png
Add translations
- Name and description in language files

Adding a New NPC

Create model
- Model: Common/NPC/Intelligent/[NPCName]/
- Model config: Server/Models/NPC/[NPCName].json
Add sounds
- Idle, move, conversation sounds: Common/Sounds/NPC/[NPCName]/
- Sound events: Server/Audio/SoundEvents/SFX/NPC/[NPCName]/
Define NPC behavior
- Attitude: Server/NPC/Attitude/[NPCName].json
- Role: Server/NPC/Roles/[NPCName].json
- Group (if applicable): Server/NPC/Groups/[GroupName].json
Create spawner egg
- Egg item: Server/Item/Items/EggSpawner/[NPCName].json
Add loot table
- Drops: Server/Drops/NPC/[NPCName].json

Getting Help

If you need assistance:

Check Documentation
- Read the Project Structure guide
- Review existing similar content as examples
Ask Questions
- Open a GitHub issue with the “question” label
- Provide context and what you’ve already tried
Join Community
- Check the repository discussions
- Connect with other contributors

Code of Conduct

Be respectful and constructive
Welcome newcomers and help them learn
Credit sources and inspiration
Follow licensing requirements
Collaborate openly and transparently

Attribution

When contributing assets or code from external sources:

Ensure you have rights to use the content
Provide attribution in commit messages or documentation
Respect Star Wars intellectual property (for fan-made, non-commercial use)
Credit original creators of adapted or modified content

This is a fan-made mod for educational and entertainment purposes. Always respect intellectual property rights and fair use guidelines.

Thank You!

Thank you for contributing to Orbis Galactic! Your efforts help bring the Star Wars universe to Hytale. May the Force be with you!

Getting Started

Content

Configuration

Development

​Getting Started

​Project Information

​How to Contribute

​Types of Contributions

​Development Environment Setup

​Required Tools

​Repository Setup

​Contribution Workflow

​1. Planning Your Contribution

​2. Creating Content

​Naming Conventions

​File Organization

​3. Creating Models

​Blockbench Workflow

​4. Adding Sounds

​Audio Requirements

​Audio Workflow

​5. Creating Item Definitions

​Item JSON Structure

​6. Adding Translations

​7. Testing Your Changes

​8. Submitting Your Contribution

​Commit Guidelines

​Pull Request Process

​Content Guidelines

​Star Wars Canon Adherence

​Balance Considerations

​Quality Standards

​Common Tasks

​Adding a New Lightsaber

​Adding a New Block

​Adding a New NPC

​Getting Help

​Code of Conduct

​Attribution

​Thank You!

Build docs developers (and LLMs) love

Getting Started

Project Information

How to Contribute

Types of Contributions

Development Environment Setup

Required Tools

Repository Setup

Contribution Workflow

1. Planning Your Contribution

2. Creating Content

Naming Conventions

File Organization

3. Creating Models

Blockbench Workflow

4. Adding Sounds

Audio Requirements

Audio Workflow

5. Creating Item Definitions

Item JSON Structure

6. Adding Translations

7. Testing Your Changes

8. Submitting Your Contribution

Commit Guidelines

Pull Request Process

Content Guidelines

Star Wars Canon Adherence

Balance Considerations

Quality Standards

Common Tasks

Adding a New Lightsaber

Adding a New Block

Adding a New NPC

Getting Help

Code of Conduct

Attribution

Thank You!