Modern, cross-platform graphics and multimedia framework for C# with .NET NativeAOT

Sokol.NET is a comprehensive C# binding and application framework built on top of the Sokol headers, providing a modern, high-performance graphics API with support for desktop, mobile, and web platforms.

⚠️ Development Status: This project is under ongoing development, primarily driven by the needs of my internal projects. Future development beyond my personal technical requirements will depend on public interest and community contributions.

✨ Try all 38 examples in your browser →

Experience Sokol.NET's capabilities instantly with interactive WebAssembly examples. No installation required!

📲 Download from Google Play Store | 📂 View Source Code

The Sokol.NET Sample Browser is now available on Google Play! Experience 11 interactive demos directly on your Android device, showcasing:

• 🎮 3D Graphics - Rotating cube, GLTF viewer with 12 models, offscreen rendering, instancing
• 🎨 Shader Effects - Real-time raymarching and procedural ocean shaders
• ⚛️ Physics - Interactive Box2D simulation
• 🖼️ Textures - Dynamic textures (Conway's Game of Life), PNG loading, cubemap skybox
• 📐 Advanced Rendering - Signed Distance Field (SDF) rendering

All powered by .NET NativeAOT for near-native performance on Android devices.

• Cross-Platform: Deploy to Windows, macOS, Linux, Android, iOS, and WebAssembly from a single codebase
• High Performance: Leverages .NET NativeAOT for near-native performance with zero overhead
• Modern Graphics: Unified API supporting Direct3D 11, Metal, OpenGL, OpenGL ES, and WebGL
• Rich Examples: 38 example applications demonstrating various graphics techniques and features
• Production Ready: Includes ImGui, Assimp, glTF, Spine, Ozz animation, and more integrations

• sokol_gfx: Modern 3D graphics API abstraction
• sokol_app: Unified application/window management
• sokol_audio: Cross-platform audio playback
• sokol_fetch: Asynchronous resource loading
• sokol_time: High-precision timing
• sokol_gl: OpenGL 1.x style immediate mode rendering
• sokol_gp: 2D graphics painter API
• sokol_debugtext: Text rendering for debugging
• sokol_shape: Procedural 3D shape generation

• Dear ImGui (cimgui): Immediate mode GUI toolkit
• cgltf: glTF 2.0 loader
• Basis Universal: GPU texture compression
• fontstash: Dynamic font rendering
• stb_image: Image loading (PNG, JPG, etc.)
• pl_mpeg: MPEG1 video playback

These libraries are available as separate dynamic libraries that can be loaded when needed:

• Assimp: 3D model loading (40+ formats) - Load dynamically via native library configuration
  • Note: May have performance issues on low-tier Android devices. Consider using GltfViewer (SharpGLTF-based) or cgltf for better compatibility and performance.
• Spine: 2D skeletal animation runtime - Load dynamically via native library configuration
• Ozz-animation: 3D skeletal animation system - Load dynamically via native library configuration

See example projects (assimp_simple, spine_simple, ozz_shdfeatures) and their Directory.Build.props files for configuration details.

Recommended: For glTF 2.0 models, use the GltfViewer example - a production-ready, full-featured glTF viewer with PBR rendering, animations, and advanced material support.

The examples/ folder contains 38 sample applications demonstrating various features:

• clear - Basic window and clear color
• cube - Rotating 3D cube with texture
• instancing - Hardware instancing demonstration
• offscreen - Render-to-texture techniques
• mrt - Multiple render targets
• shadows - Shadow mapping implementation

• AndroidSokolApp - Native .NET for Android integration using Sokol GFX without Sokol App, demonstrating GLSurfaceView integration and manual OpenGL context management

• IOSSokolApp - Native .NET for iOS integration using Sokol GFX without Sokol App, demonstrating MTKView integration and manual Metal context management

• SkiaSokolApp - SkiaSharp sample gallery with 40+ interactive samples (shapes, text, images, filters, shaders, animations)
• sgl - 2D immediate mode rendering
• sgl_lines - Line rendering techniques
• shapes_transform - 2D transformations
• dyntex - Dynamic texture updates

• debugtext - Debug text overlay
• debugtext_context - Multiple text contexts
• fontstash - TrueType font rendering
• fontstash_layers - Layered text effects

• assimp_simple - Basic 3D model loading
• assimp_animation - Skeletal animation with Assimp
• assimp_scene - Complex scene loading
• cgltf - glTF 2.0 model loading
• CGltfViewer - Full-featured glTF 2.0 viewer using the native cgltf C library — zero-allocation loading, full PBR pipeline, skinning, morphing, IBL, bloom, and 11+ material extensions; runs on Desktop, Web, iOS, and Android
• GltfViewer - Full-featured glTF 2.0 viewer using the managed SharpGLTF C# library — PBR rendering, animations, and advanced material support; best suited for Desktop and Web
• ozz_shdfeatures - Ozz animation system with shader features

• spine_simple - Basic Spine animation
• spine_skinsets - Spine skin swapping
• spine_inspector - Spine animation debugger

• loadpng - PNG texture loading
• basisu - Basis Universal GPU textures
• cubemap_jpeg - Cubemap textures
• cubemaprt - Render-to-cubemap
• miprender - Mipmap generation
• vertextexture - Vertex texture fetch
• texview - Texture viewer utility
• sdf - Signed distance field rendering

• cimgui - Dear ImGui integration
• imgui_usercallback - Custom ImGui rendering

• JoltPhysics - 10,000 dynamic physics bodies with GPU instancing and multithreading
• bepuphysics - BEPUphysics v2 integration with .NET physics engine

• drawcallperf - Draw call performance testing
• plmpeg - MPEG1 video playback
• ShaderToyApp - Multi-shader gallery with 7 fragment shaders

Some examples in this repository (spine_simple, spine_skinsets, spine_inspector) use the Spine runtime library.

Important for Users: While you are free to evaluate and build these examples, if you wish to use Spine in your own projects, you will need to purchase a Spine license. The Spine Runtimes are covered by the Spine Runtimes License Agreement.

This repository's maintainer has a valid Spine license for development and distribution of these examples.

• .NET 10.0 SDK or later
• CMake 3.29.0 or later (required for building native libraries)
• Visual Studio Code (primary development IDE)
  • Required for Android and iOS development (build/install/debug)
  • Supports all platforms: Desktop, Web, Android, and iOS
  • Alternative IDEs (Visual Studio, Rider) support Desktop and Web only
• wasm-tools-net8 workload (for WebAssembly development): dotnet workload install wasm-tools-net8
• Platform-specific toolchains:
  • Windows: Visual Studio 2022 Build Tools
  • macOS: Xcode Command Line Tools
  • Linux: GCC/Clang
  • Android: Android SDK & NDK 27+ (NDK 29+ recommended for Google Play)
    • Required for Google Play: NDK 27+ includes 16KB page size support (Android 15+ / API 35+ requirement)
    • The build system automatically selects the best available NDK version
  • iOS: Xcode 14+

git clone --recursive https://github.com/elix22/Sokol.NET.git
cd Sokol.NET

# Configure Git to automatically update submodules (IMPORTANT!)
git config submodule.recurse true

# Register the repository (creates ~/.sokolnet_config)
./register.sh  # macOS/Linux
# or
register.bat   # Windows

⚠️ Important: The git config submodule.recurse true command is required to automatically update nested submodules (like cimgui/imgui) when you pull changes. Without this, you'll need to manually run git submodule update --init --recursive after every git pull.

📘 Complete VS Code Run Guide with Screenshots - Get started instantly with step-by-step instructions for running applications on all platforms.

VS Code is the primary development environment with full support for all platforms.

Desktop & Web: Press F5 and select your platform and example.

Android & iOS: Use Command Palette (Cmd+Shift+P / Ctrl+Shift+P) → Tasks: Run Task:

Android Tasks:

• Android: List Devices - List all connected Android devices
• Android: Build APK - Build release/debug APK
• Android: Build AAB - Build release/debug Android App Bundle
• Android: Install APK - Build and install APK to selected device
• Android: Install AAB - Build and install AAB to selected device

iOS Tasks:

• iOS: List Devices - List all connected iOS devices
• iOS: Build - Build release/debug iOS app
• iOS: Install - Build and install to selected iOS device

Desktop (works with Visual Studio, Rider, or command line):

cd examples/cube
dotnet build cube.csproj -t:CompileShaders
dotnet build cube.csproj
dotnet run -p cube.csproj

Note: Visual Studio and Rider support Desktop and Web development only. For Android and iOS, use Visual Studio Code.

📘 Complete Project Creation Guide - Learn how to create standalone Sokol.NET projects.

Create a new standalone project outside the repository:

Using VS Code:

1. Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
2. Select Tasks: Run Task → Create New Project
3. Enter project name (e.g., my_game)
4. Enter destination path (must be outside this repository)

Using Command Line:

dotnet run --project tools/SokolApplicationBuilder -- \
  --task createproject \
  --project my_game \
  --destination /path/to/projects

The project will be created with full VS Code configuration, ready to open and run independently.

dotnet run --project tools/SokolApplicationBuilder -- \
  --task build --architecture android --type release \
  --path examples/cube --install --interactive

dotnet run --project tools/SokolApplicationBuilder -- \
  --task build --architecture ios --type release \
  --path examples/cube --install --interactive

dotnet run --project tools/SokolApplicationBuilder -- \
  --task build --architecture web \
  --path examples/cube

See docs/web-server-setup.md for running WebAssembly apps locally.

Comprehensive documentation is available in the docs/ folder:

• Visual Studio Code Run Guide ⭐ - Step-by-step guide with screenshots for running apps on all platforms
• Shader Programming Guide 🎨 - Complete guide to writing cross-platform shaders with sokol-shdc
• Creating New Projects 🚀 - How to create standalone Sokol.NET projects outside the repository
• Creating New Examples 🆕 - How to create new example projects from template

• Android

  • Android Properties Configuration
  • Android Screen Orientation
  • Android Device Selection
  • AAB Build Guide
  • Android Keyboard Implementation

• iOS

  • iOS Device Selection & Installation
  • iOS Properties Configuration

• WebAssembly

  • WebAssembly Local Server Setup
  • WebAssembly Browser Guide
  • Browser Cache Issues

• Build System Documentation - Complete build system reference
• Quick Build Reference - Common build commands
• Sokol Application Builder - Build tool documentation
• Multi-Device Install - Installing to multiple devices

• App Icon Configuration
• Icon Quick Start
• App Version Configuration
• Package Prefix Configuration
• Project Template

• C Internal Wrappers Auto-Generation
• WebAssembly Struct Return Workaround
• Output Path Implementation

📖 Full Documentation Index

Sokol.NET/
├── examples/          # 36 example applications
├── src/              # C# bindings and core libraries
├── ext/              # Native C/C++ dependencies
│   ├── sokol/       # Sokol headers
│   ├── cimgui/      # ImGui C bindings
│   ├── assimp/      # 3D model loader
│   ├── cgltf/       # glTF loader
│   ├── spine-c/     # Spine runtime
│   └── ozz-animation/ # Animation system
├── libs/             # Prebuilt native libraries
│   ├── windows/
│   ├── macos/
│   ├── linux/
│   ├── android/
│   ├── ios/
│   └── emscripten/
├── tools/            # Build tools and utilities
│   └── SokolApplicationBuilder/
├── bindgen/          # C# binding generator
├── docs/             # Documentation
└── templates/        # Project templates

Native Sokol libraries are pre-built and included in the libs/ folder. To rebuild:

.\scripts\build-vs2022-windows.ps1

./scripts/build-xcode-macos.sh

./scripts/build-linux-library.sh

./scripts/build-android-sokol-libraries.sh

./scripts/build-ios-sokol-library.sh

See docs/BUILD_SYSTEM.md for detailed build instructions.

Contributions are welcome! Please ensure:

• Code follows existing style and conventions
• All platforms continue to build successfully
• Examples run without errors
• Documentation is updated for new features

This project is licensed under the MIT License. See individual library folders for their respective licenses:

• Sokol: zlib/libpng license
• ImGui: MIT License
• Assimp: BSD 3-Clause License
• Spine: Spine Runtime License

Built on top of these excellent libraries:

• Sokol by Andre Weissflog
• Dear ImGui by Omar Cornut
• Assimp - Open Asset Import Library
• cgltf by Johannes Kuhlmann
• Spine Runtimes by Esoteric Software
• Ozz-animation by Guillaume Blanc

• Issues: GitHub Issues
• Author: Eli Aloni (elix22)

Get started now: Clone the repository, run ./register.sh, and explore the examples!