Nez 2D Game Framework

Nez is a feature-rich 2D framework built on top of MonoGame/FNA. It provides a comprehensive suite of tools for 2D game development, including:

• Entity Management: A Scene/Entity/Component system with Component render layer tracking.
• Physics & Collision:
  • AABB, circle, and polygon collision/trigger detection.
  • SpatialHash for fast broadphase physics lookups (used internally for raycasts and overlap checks).
  • Farseer Physics (Box2D-based) integration for full physics simulations.
  • Verlet physics bodies for particle-based constraints.
• Task Management:
  • Core.startCoroutine for efficient coroutines to handle tasks across multiple frames.
  • Core.schedule for delayed and repeating tasks.
• Rendering & Visuals:
  • Extensible rendering system with support for custom Renderers, PostProcessors, and custom sorters.
  • Deferred lighting engine with normal map support.
  • Tween system for animating fields (int, float, Vector, quaternion, color, rectangle).
  • Sprite support (animations, scrolling, repeating, and trails).
  • Line renderer with configurable end caps.
  • Particle system with Particle Designer file support.
• Debugging Tools:
  • In-game debug console (accessible via the tilde ~ key) with visual physics debugging, asset tracking, and profiling.
  • In-game Component inspector: use the inspect ENTITY_NAME command in the debug console to edit properties and call methods.
  • Dear ImGui integration for custom debug panels via attributes.
• Data & Pathfinding:
  • Serialization via Nez.Persistence using JSON, NSON (strongly typed, human-readable), or binary formats, supporting polymorphic classes and reference resolution.
  • Pathfinding via Astar and Breadth First Search for tilemaps or custom formats.
• Scene Management:
  • Per-Scene content managers that automatically unload scene-specific content upon scene changes.
  • Customizable Scene transition system with built-in transitions.
• Events: Optimized Emitter class for core and custom events.

Nez provides a Verlet physics system designed for visual effects and interactions rather than full rigid-body simulation.

Key Concepts:

• Simulation vs. Rendering: The Verlet system handles physics simulation only. It is not a renderer; you must manually render meshes or textures based on the simulation data. You can use _world.DebugRender(batcher) for quick visualization during development.
• Interaction: Verlet objects can interact with standard Nez Colliders, but for efficiency, Verlet objects do not interact with each other.
• Core Components: The simulation is built from Particles (which have mass and can be pinned or set to collide with Nez Colliders) and Constraints (mathematical rules that adjust particle positions).

To run the simulation, you must create a World object and call its Update() method within your game loop.

public class VerletDemo : RenderableComponent, IUpdatable
{
	public override float Width { get { return 800; } }
	public override float Height { get { return 600; } }

	World _world;

	public override void OnAddedToEntity()
	{
		// create the verlet world which handles simulation
		_world = new World( new Rectangle( 0, 0, 800, 600 ) );

		// add a couple built-in Composite objects
		_world.AddComposite( new Tire( new Vector2( 100, 100 ), 50, 20 ) );
		_world.AddComposite( new Cloth( new Vector2( 10, 10 ), 200, 100 ) );
	}

	public void Update()
	{
		_world.Update();
	}

	public override void Render( Batcher batcher, Camera camera )
	{
		_world.DebugRender( batcher );
	}
}

Skins act as containers for UI resources (colors, textures, fonts, and styles). You can use them to quickly apply consistent styling to elements.

Ways to use Skins:

1. Default Skin: Use Skin.CreateDefaultSkin for quick prototyping.
2. JSON Configuration: Define colors, atlases (LibGdxAtlases or TextureAtlases), and specific style types (e.g., ButtonStyle, WindowStyle) in a JSON file. This can be processed by the UI Skin Importer in the Pipeline tool.
3. Programmatic Creation: Build a skin in code using skin.Add() and skin.GetDrawable().

When using a skin, you can fetch a specific style by name: skin.Get<T>( "styleName" ). Alternatively, passing the Skin object directly to an element constructor will cause it to look for a style named "default" within that skin.

var skin = new Skin( "skins/uiskinconfig", Core.Content );

// Fetch style by specific type and name
var button = new Button( skin.Get<TextButtonStyle>( "default" ) );

// Or pass the skin directly to use the "default" style
var button = new Button( skin );

// Using a specific style name from JSON
var bar = new ProgressBar( 0, 1, 0.1f, vertical, skin.Get<ProgressBarStyle>( "default-vertical" ) );

// Using a style that relies on colors defined in the JSON
var button = new Button( skin.Get<ButtonStyle>( "colored" ) );
table.Add( button ).SetMinWidth( 100 ).SetMinHeight( 30 );

You can create custom transition effects by subclassing SceneTransition. Transitions generally fall into two categories:

1. One-part transitions: Obscure the screen with a render of the previous Scene, load the new Scene, and then transition from the old render to the new Scene's render (e.g., sliding the old render off-screen).
2. Two-part transitions: Perform an initial effect (e.g., fade to black), load the new Scene, and then transition to displaying the new Scene.

Implementation Steps

• Constructor: Load any required Effect or textures here. If the transition is for a new Scene, accept a Func<Scene> sceneLoadAction.
• OnBeginTransition(): Override this method to define the transition logic. It runs in a coroutine.
  • For two-part transitions, perform the first part (e.g., fade to black) before yielding to load the next scene.
  • Use yield return Core.StartCoroutine( LoadNextScene() ) to load the next Scene. Nez handles the _isNewSceneLoaded flag automatically for both intra-Scene and inter-Scene transitions.
  • Call TransitionComplete() to end the transition and trigger cleanup.
• Render(Batcher batcher): Override this to control the final render output every frame. You can access previousSceneRender (the last render of the previous Scene) and use the _isNewSceneLoaded flag to determine which part of the transition is active.
• Cleanup: Unload Effects or Textures in OnBeginTransition after calling TransitionComplete(), or override TransitionComplete and call base! to perform cleanup.

Helper Method

TickEffectProgressProperty is a helper that allows you to yield in a coroutine to animate an Effect parameter (typically named _progress) from 0 to 1 or 1 to 0 using a specified duration and EaseType.

public class SuperTransition : SceneTransition
{
	public float Duration = 1f;
	public EaseType EaseType = EaseType.QuartOut;

	Effect _effect;
	Rectangle _destinationRect;

	public SuperTransition( Func<Scene> sceneLoadAction ) : base( sceneLoadAction, true )
	{
		_destinationRect = previousSceneRender.Bounds;
		_effect = Core.content.loadEffect( "TransitionEffect.mgfxo" );
	}

	public override IEnumerator OnBeginTransition()
	{
		yield return Core.StartCoroutine( LoadNextScene() );
		yield return Core.StartCoroutine( TickEffectProgressProperty( _effect, duration, easeType ) );
		TransitionComplete();
		Core.Content.UnloadEffect( _effect );
	}

	public override void Render( Batcher batcher )
	{
		Core.graphicsDevice.SetRenderTarget( null );
		batcher.Begin( BlendState.NonPremultiplied, Core.DefaultSamplerState, DepthStencilState.None, null, _effect );
		batcher.Draw( previousSceneRender, _destinationRect, Color.White );
		batcher.End();
	}
}