NeutrinoParticles.V1_2.MonoGame.DX 1.0.6

NeutrinoParticles.V1_2.MonoGame

MonoGame integration for NeutrinoParticles real-time particle effects (format v1.2).

Installation

DirectX (Windows/Xbox desktop):

dotnet add package NeutrinoParticles.V1_2.MonoGame.DX

OpenGL (cross-platform: Linux, macOS, mobile):

dotnet add package NeutrinoParticles.V1_2.MonoGame.GL

The core runtime (NeutrinoParticles.V1_2) is installed automatically as a dependency.

Choosing DX or GL

Pick one package for your build:

• NeutrinoParticles.V1_2.MonoGame.DX — for MonoGame.Framework.WindowsDX projects (Windows / Xbox desktop). Renders particles from a data texture read in the vertex shader (no per-frame CPU geometry).
• NeutrinoParticles.V1_2.MonoGame.GL — for MonoGame.Framework.DesktopGL projects (Linux, macOS, mobile). Uses a vertex-attribute path for wider device support.

Both expose the same NeutrinoParticles.MonoGame API — your game code is identical either way. Match the package to the MonoGame framework your project already references.

Compatibility: target frameworks net452, netcoreapp3.1, net8.0-windows; built against MonoGame 3.8.0.1641.

Requirements

CS1.2 requires GraphicsProfile.HiDef — it uses float vertex attributes and a 32-bit index buffer, which are HiDef-only. Set the profile on your GraphicsDeviceManager before the first frame; otherwise creating the Context throws with a clear message.

public Game1()
{
    var graphics = new GraphicsDeviceManager(this);
    graphics.GraphicsProfile = GraphicsProfile.HiDef; // required by CS1.2
    // ...
}

The default MonoGame project template uses GraphicsProfile.Reach, so this line is easy to miss — the effect fails to initialize until you switch to HiDef.

Export Target in Editor

In the NeutrinoParticles Editor, set the export target to C# v1.2.

After export you get a .cs file (e.g. MyEffect.cs) containing the effect model class. Add this file to your C# project.

Quick Start

In your Game class:

public class Game1 : Game
{
    private NeutrinoParticles.MonoGame.Context neutrinoContext_;
    private NeutrinoParticles.MonoGame.ParticleEffect effect_;

    protected override void LoadContent()
    {
        neutrinoContext_ = new NeutrinoParticles.MonoGame.Context(
            GraphicsDevice,
            texturesBasePath: "particles/",
            generateNoise: true
        );

        var effectModel = new NeutrinoParticles.MonoGame.ParticleEffectModel(
            neutrinoContext_,
            new NeutrinoParticles.Effect_MyCoolEffect(),
            Content
        );

        effect_ = new NeutrinoParticles.MonoGame.ParticleEffect(
            effectModel,
            position: new Vector3(400, 300, 0)
        );
    }

    protected override void Update(GameTime gameTime)
    {
        effect_.Update(gameTime);
    }

    protected override void Draw(GameTime gameTime)
    {
        effect_.Draw();
    }

    protected override void UnloadContent()
    {
        neutrinoContext_?.Shutdown();
    }
}

Context Options

The Context constructor accepts:

new NeutrinoParticles.MonoGame.Context(
    GraphicsDevice graphicsDevice,
    string texturesBasePath = "",   // prefix prepended to texture names referenced by exported effects
    bool generateNoise = false,     // build turbulence noise on construction (needed by effects that use it)
    bool axisYGoesUp = false,       // set true if your app's Y axis goes up (default: Y goes down)
    bool useInstancing = false      // GL only — see below
);

• texturesBasePath — prepended to every texture path baked into the exported effect. Point it at where those textures live for your ContentManager (e.g. "particles/"). It is a name prefix, not a filesystem path.

• useInstancing (GL backend only) — chooses how quad corners reach the GPU:

  • false (default) — X4-replication: each particle record is expanded to 4 vertices on the CPU. Proven robust on stock DesktopGL.
  • true — instancing: one shared 4-corner buffer + a per-instance record stream (DrawInstancedPrimitives), less vertex bandwidth. Opt-in until per-backend GL reliability is confirmed, so try it and verify on your target devices.

  The DX backend ignores useInstancing — it always uses the data-texture path.

Common Issues

• Crash on Context creation (HiDef required): Set GraphicsDeviceManager.GraphicsProfile = GraphicsProfile.HiDef before ApplyChanges(). The default template uses Reach, which CS1.2 does not support (see Requirements).
• No particles visible: Check that the export target in the editor is set to C# v1.2. Verify texturesBasePath points to the correct textures directory in your Content pipeline.
• Turbulence not working: Set generateNoise: true when creating the context.

HDR Bloom (optional add-on)

Add a scene-preserving HDR glow that matches the editor preview with the NeutrinoParticles.V1_2.MonoGame.Bloom.DX / .GL add-on: render the effect into an HDR RenderTarget2D, then ProcessBloom + RenderResult to the backbuffer. Only particle colour above 1.0 glows. Requires GraphicsProfile.HiDef.

Documentation

Full documentation at neutrinoparticles.com.

License

Copyright (c) Yurii Miroshnyk. All rights reserved.