Visual Effects & Contexts Overview

Welcome to the Cosmos Engine! This guide covers the core concepts of the node editor's Context system.

---

Understanding Project Contexts (Tabs)

When you open the Cosmos Node Editor, you will notice three primary tabs: Material, Trail, and Beam. These are called Contexts.

In traditional Minecraft modding, generating a shape and coloring it are deeply intertwined. Cosmos splits these into two distinct layers for maximum performance and reusability:

1. Geometry Contexts (Trails & Beams): Calculate the physical 3D shape, size, and math.
2. Material Context: Calculates the colors, textures, glowing effects, and actual pixels drawn on that shape.

Because of this split, Geometry Contexts do not know what color is, and Material Contexts do not know what shape they are being drawn on.

1. The Material Context

Material Context

The Material Context is the heart of your visual effect. It is responsible for generating the actual GLSL shader code that runs on the GPU.

• Primary Nodes: OUTPUT_FRAG (for pixel colors/alpha) and OUTPUT_VERT (for vertex displacement/scaling).
• Allowed Nodes: Almost all nodes (Math, Colors, Textures, Noise, UVs).
• Preview Settings: You can change the base preview shape (e.g., Cube, 2D Quad) to see how your shader reacts to different surfaces. This setting is strictly for the IDE and does not export to the game.

Render State Settings: The Material Context also controls the OpenGL Render State. These settings dictate how your geometry interacts with the world behind it:

• Blend Mode: OPAQUE (Solid), TRANSLUCENT (Soft Alpha), ADDITIVE (Glowing Magic), or MULTIPLY (Dark Shadows).
• Cull Mode: BACK (Standard), FRONT, or NONE (Double-sided, required for flat planes or ribbons).
• Depth Test: LEQUAL (Standard depth sorting) or ALWAYS (Renders through walls like an X-Ray).
• Depth Write (Z-Write): Should this material block objects behind it? Usually set to false for Translucent and Additive materials to prevent visual glitches.
• Alpha Cutoff: Discards pixels below this transparency threshold, perfect for crisp, intersecting pixel-art without depth-sorting issues.

2. The Trail Context

Trail Context

The Trail Context calculates the physical 3D ribbon that follows an entity or projectile through the world. It is evaluated purely via math, which is then translated into Java code.

• Primary Node: TRAIL_ENDPOINT.
• Allowed Nodes: Only Math, Time, and Vector nodes. Color and Texture nodes are forbidden here.
• Node Inputs:
  • width: The thickness of the ribbon at any given point.
  • orbit_offset: Pushes the ribbon away from the center of the entity (useful for swirling helix effects).

Trail Settings:

• Segments: The resolution of the trail. Determines how many historical points the trail remembers. Higher values (e.g., 50) create very long, smooth trails but require slightly more memory. Lower values (e.g., 10) are great for short, fast swings.

3. The Beam Context

Beam Context

The Beam Context calculates a continuous, volumetric 3D cylinder stretching directly from a starting point (like a player's hand) to an endpoint (like a target block).

• Primary Node: BEAM_ENDPOINT.
• Allowed Nodes: Only Math, Time, and Vector nodes. Color and Texture nodes are forbidden here.
• Node Inputs:
  • radius_curve: The thickness of the cylinder. Can be driven by Time to make the beam pulse.
  • offset_x, y, z: Pushes the beam off its direct source-to-target trajectory, allowing for bent, erratic, or wavy lightning beams.

Beam Settings:

• Radial Segments (Shape): Controls the cross-section of the beam (3 = Triangle, 4 = Square, 8 = Octagon, 16+ = Smooth Cylinder).
• Length Segments (Smoothness): Controls how many subdivisions the beam has along its length. Required if you are adding mathematical offsets to make the beam bend smoothly.

The Golden Rule: Use the Trail/Beam tabs to change the Shape. Use the Material tab to change the Paint. You can reuse a single "Fire" material across multiple Trail and Beam geometries!