How to Report a Bug

If you discover a problem with Theatrical: Realistic Pack (TRP), providing clear information about the issue makes it much easier to reproduce, investigate and fix.

Before reporting a bug, try to confirm that the problem is actually caused by TRP and gather as much useful information as possible.

REPORT IT HERE !

Before Reporting

Before creating a bug report, check the relevant troubleshooting pages and verify the basic installation.

Make sure you are using:

• The correct Minecraft version
• The correct TRP build
• A compatible Forge version
• The correct Java version
• Required dependencies for your TRP branch
• Matching client and server versions in multiplayer

For Minecraft 1.20.1, TRP requires Theatrical. The newer TRP branches do not have mandatory external mod dependencies.

Try to Reproduce the Problem

A good bug report should explain exactly how the issue can be reproduced.

Try to find the smallest sequence of actions that consistently causes the problem.

For example:

1. Place a MegaPointe.
2. Set Mode 1.
3. Patch it to Universe 1 / Address 1.
4. Send DMX.
5. Select a rotating gobo.
6. Enable prism.
7. The projection disappears.

This is much more useful than:

MegaPointe is broken.

If the problem only happens sometimes, mention that as well.

Include Your Versions

Always include:

• TRP Version
• Minecraft Version
• Forge Version
• Java Version

If using Minecraft 1.20.1, also include:

• Theatrical Version

If the problem started after an update, include both:

• Previous working TRP version
• Current problematic TRP version

Include Other Mods

If you are using other mods, include your mod list or mention the mods most likely to interact with the issue.

This is particularly important for mods that affect:

• Rendering
• Shaders
• Networking
• Truss / Rigging
• World Geometry
• Multiplayer

If possible, test the problem in a minimal installation.

Minecraft 1.20.1

Forge
Theatrical
TRP

Newer TRP Branches

Forge
TRP

If the problem disappears in a clean installation, another mod or configuration may be involved.

Include Logs

Logs are extremely useful when investigating:

• Crashes
• Startup failures
• Rendering errors
• Network problems
• Server problems
• Unexpected exceptions

Useful files include:

latest.log
debug.log

and any relevant file inside:

crash-reports/

Whenever possible, provide the complete file rather than only a screenshot of the final error.

Crash Reports

If Minecraft generates a crash report, include it.

A crash report can contain information about:

• The exact exception
• Affected classes
• Loaded mods
• Minecraft environment
• Thread state
• Stack trace
• Hardware / Java environment

Do not remove sections of the report unless they contain information you specifically need to keep private.

Fixture Bugs

For problems involving a fixture, include:

• Fixture Model
• Fixture Mode / Personality
• DMX Universe
• DMX Address
• Theatrical Network
• Feature being used

For example:

Fixture: Spiider
Mode: Mode 8 - Pixel RGBA
Universe: 3
Address: 101
Problem: Pixel 7 does not follow the expected colour

TRP implements fixture functionality individually, so knowing the exact model and personality is important.

DMX Problems

If the issue involves DMX, include:

• Fixture
• Fixture Personality
• Address
• Universe
• Rack Node
• Rack Port
• Source Universe
• Protocol
• External Lighting Software

For example:

Protocol: Art-Net
Software: MagicQ
Source Universe: 0
Rack: Robe Rack Data 8 RDM
Port: 1
Fixture: FORTE
Fixture Universe: Generated Port 1 Universe
Address: 1
Mode: Mode 1
Rack Status: LIVE
Fixture Status: NO DMX

This makes it much easier to identify whether the problem is related to:

• External DMX
• Rack routing
• Universe mapping
• Fixture patch

Art-Net / sACN Problems

For networking issues, also include information about:

• Singleplayer or Dedicated Server
• Operating System
• Wired Ethernet or Wi-Fi
• Network Interface
• Firewall
• Art-Net or sACN
• Whether the Rack shows Live / Stale / No Data

TRP’s Rack Nodes expose status information for incoming network data, including Live, Stale and No Data conditions.

If the Rack shows LIVE, mention it explicitly.

That information immediately helps separate external network problems from fixture-routing problems.

Rendering Problems

For rendering bugs, include the relevant TRP graphics configuration.

Important settings include:

• Model Quality
• Detailed Model Distance
• Beam Occlusion Mode
• Beam Opacity
• Maximum Beam Reach
• Volumetric Beam Segments
• Projection Steps

TRP exposes independent controls for fixture models, beams, projections and impact lighting.

External Shaders

If you are using an external shader pack, include:

• Shader name
• Shader version

Also test whether the same problem happens without the external shader.

External shader compatibility is not guaranteed.

If the problem disappears when the shader is disabled, mention this clearly in the report.

Diagnostic Options

For difficult rendering problems, TRP includes diagnostic configuration options such as:

renderPerformanceProfiling=false
diagnosticRenderProfiling=false

debugDisablePhysicalFixtureModels=false
debugDisableFixtureBeams=false
debugDisableFixtureProjections=false
debugDisableImpactLights=false

These can help determine whether the problem is related to:

• Fixture Models
• Volumetric Beams
• Projections
• Impact Lights

If you test any of these options, include the result in your bug report.

Custom Gobo Bugs

For problems involving Custom Gobos, include:

• Fixture Model
• Gobo Wheel
• Factory or Custom Gobo
• Engraving Resolution
• Whether the gobo was drawn or imported
• PNG or SVG if imported
• Whether the issue affects one fixture or several

Custom Gobos can be created at:

• 64 × 64
• 96 × 96
• 160 × 160
• 256 × 256

and the resulting mask is stored on the gobo item.

RoboSpot Problems

For RoboSpot issues, include:

• Fixture Model
• Number of bound fixtures
• Active Camera Fixture
• Control Policy
• Whether the problem affects movement or optics

Remember that only the following fixtures are supported in the reviewed implementation:

• BMFL Blade
• BMFL Spot
• BMFL Wash
• ESPRITE FS
• FORTE
• PAINTE

Do not report unsupported fixtures failing to appear in RoboSpot as a bug.

FollowMe Problems

For FollowMe problems, include:

• Target type
• Fixture Model
• Number of selected fixtures
• Auto Focus state
• Auto Zoom state
• Whether the tracker is carried or attached to an entity

Supported fixtures are:

• BMFL Blade
• BMFL Spot
• BMFL Wash
• FORTE
• PAINTE

A target fixture must also be loaded and have a valid DMX address greater than zero.

Performance Reports

If reporting poor performance, include:

• CPU
• GPU
• System RAM
• Minecraft RAM allocation
• Screen resolution
• Fixture count
• Approximate active beam count
• Pixel fixtures being used
• TRP graphics configuration
• Minecraft render distance
• External shaders
• Approximate FPS

If possible, describe the scene where performance is worst.

For example:

80 fixtures placed
45 active beams
12 Spiiders in Pixel RGBA
6 Tetra2 in Pixel RGBW
Realistic Occlusion
96-block beam range
1440p
45-50 FPS

This is much more useful than simply reporting:

TRP has bad performance.

Screenshots & Video

Screenshots and videos are especially useful for visual problems.

Include them when reporting:

• Incorrect beams
• Projection artifacts
• Wrong fixture models
• Pixel problems
• Gobo rendering issues
• Rigging problems
• GUI problems
• RoboSpot camera issues

A short video can sometimes explain an animation or movement problem much better than text.

World Information

If the problem only happens in one world, mention it.

Useful information includes:

• Singleplayer or Multiplayer
• New or Existing World
• World migrated between TRP versions
• World migrated between Minecraft versions
• Approximate location / dimension of the problem
• Whether the issue happens in a new test world

If the problem cannot be reproduced in a new world, the existing world’s saved state may be relevant.

Do Not Send the World Unless Requested

For most bugs, logs and reproduction steps are enough.

Large Minecraft worlds should normally only be supplied if specifically requested because they can contain:

• Large amounts of unrelated data
• Other mods
• Player information
• Custom builds
• Server configuration

Start with the smallest useful set of information.

Good Bug Report Example

Title:
MegaPointe rotating gobo projection disappears with prism enabled

Minecraft:
1.20.1

Forge:
47.x

TRP:
0.13.9

Theatrical:
1.0.0-alpha.28.xxx

Fixture:
MegaPointe

Mode:
Mode 1 - 39 channels

Network:
Main Stage

Universe:
1

Address:
1

External Controller:
MagicQ via Art-Net

Rack:
Robe Rack Data 8 RDM

Rack Status:
LIVE

External Shaders:
Disabled

Steps:
1. Place MegaPointe.
2. Patch to Mode 1.
3. Open dimmer and shutter.
4. Select rotating gobo.
5. Enable prism.
6. Projection disappears.

Expected:
Gobo projection remains visible with prism enabled.

Actual:
Projection disappears immediately.

Attachments:
latest.log
debug.log
short video

The more reproducible the problem is, the easier it is to investigate.