Framework services and ecosystem quick reference
Evidence basis: source-verified at the pinned commit; tests exist (not executed for this page). Claims on this page were checked by reading the CNA source at commit 009d40f5; unless a sentence says otherwise, nothing here was built or executed. Service rows summarise CNA facts read at 009d40f5 and the owner pages linked from each row. Binding facts are those repositories' pinned revisions; application facts were read at the revisions named in the table and are evidence only for those revisions. Nothing was built or run.
This page is a map, not a manual: for each group of framework-service and sharp-runtime types it gives the public shape, the boundary that matters at CNA snapshot 009d40f5, and the deep dive that owns the exact semantics and evidence. It closes with the two kinds of repository around CNA that are most often over-read, the language bindings and the showcase applications, with the revision each statement belongs to. Use it to find the right page quickly and to avoid the most common misreadings; do not cite a row here as proof of behaviour.
How to read the rows
Each row has three parts. The public shape is what a header declares; A member with no XNA 4.0 counterpart carries the CNAEXT marker and usually, but not always, an EXT name suffix; the two are independent conventions, catalogued on the CNAEXT catalogue. The four-way vocabulary of STRICT (XNA 4.0 API), FNA-compatible, EXT (an FNA extension beyond XNA) and CNAEXT (a CNA addition with no XNA or FNA counterpart) is CNA's own glossary for the input surface (STRICT, EXT and CNAEXT members); the other rows on this page are not classified that way. The boundary is the fact that most often separates "the type exists" from "the behaviour happens here". The owner page is where the exact semantics, source links and tests are. Representation is not behaviour: every XNA type and member is represented (331/331 types, 3,627/3,627 members), which says nothing about whether a given host delivers an event, a device, a codec or a network (presence versus behaviour).
Input: keyboard, mouse, gamepad and touch
| Type group | Public shape | Boundary at this snapshot | Owner page |
|---|---|---|---|
Keyboard, KeyboardState | Snapshot state, key up/down, pressed-key enumeration; EXT helpers GetKeyNameEXT, GetScancodeNameEXT, GetKeyFromScancodeEXT, GetModStateEXT | A Keys value, a physical scancode and a layout-dependent key name are three different things; do not collapse them | input model: layouts and scancodes |
Mouse, MouseState | Position, buttons, wheel, cursor; EXT helpers such as GetGlobalPositionEXT, SetCaptureEXT and WarpGlobalEXT | Positions are in the renderer's logical coordinates; window, drawable and presentation space differ by renderer and host | logical coordinates |
GamePad, capabilities, state | Four player slots, dead-zone modes, SetVibration; EXT identity, SetLightBarEXT, SetTriggerVibrationEXT, gyro, accelerometer and touchpad readers | Device opening, hot-plug and controller mapping come from the platform; an EXT reader answers only where the controller and host provide it | gamepad extensions |
TouchPanel, TouchCollection, gestures | Per-update touch snapshot, display metadata, enabled gestures, gesture dequeue | Two different "connected" answers; coordinates pass through the same logical transform as the mouse; a desktop run without a touch device exercises the API, not physical touch | touch: two connected answers |
CNA::Input services | Clipboard, raw joysticks, haptics, host power and motion sensors | CNA extensions outside XNA's surface, with per-platform absence or refusal | raw joysticks and callbacks |
A state object that can be constructed without hardware is not evidence that a host delivered the event, nor that the selected renderer maps coordinates back into the same logical space.
Audio and media
| Type group | Public shape | Boundary at this snapshot | Owner page |
|---|---|---|---|
SoundEffect, SoundEffectInstance | Loaded or raw PCM, fire-and-forget or owned instances, volume, pitch, pan, loop, Apply3D | The 3D model is CNA's own formula over its mixer; instance and source disposal order are observable contracts | pitch and 3D, exactly |
DynamicSoundEffectInstance | Buffer-needed event and streamed 16-bit submission; CNAEXT SubmitFloatBufferEXT | Switching between 16-bit and float submission is allowed only while stopped; the other kind while playing or paused throws InvalidOperationException; frame alignment is not checked | dynamic streaming |
| XACT objects | Audio engine, wave and sound banks, cues, categories, variables, runtime parameter control | CNA parses and plays a substantial subset with its own engine; unsupported fields fail explicitly | XACT at run time |
Song, MediaPlayer, MediaLibrary | Song metadata, queued playback, shuffle, repeat, volume, position, state events, file-backed libraries | A name that resolves is not a file that plays; no Song route accepts MIDI at this snapshot | media: formats |
Video, VideoPlayer | Video metadata, play/pause/resume/stop, frame texture, volume, loop | Decoding needs the optional FFmpeg backend (CNA_ENABLE_VIDEO); without it the types exist and playback throws NotSupportedException | video and VideoPlayer |
A reader accepting a file does not prove that a mixer or video device played it, nor that its events arrived on the intended thread.
Devices and sensors
| Type group | Public shape | Boundary at this snapshot | Owner page |
|---|---|---|---|
Sensors (Accelerometer, Compass, Gyroscope, Motion) | Support and state, update interval, current value, start/stop, change events | Readings come from the selected platform's sensor service and arrive off the game thread; web targets are refused by policy | which thread delivers a reading |
VibrateController | Windows Phone vibration (Start, Stop) plus CNAEXT members: Start with an intensity, StartLeftRight, support and device-name queries | A stored request is not motor engagement; an emulator and a phone are different evidence tiers | VibrateController |
CNA::Devices | Camera, display and system information, dialogs, URL launch, locale, clipboard, tray, power | Behind an opt-in option that removes the types when off; many services report unavailable on headless or unsupported hosts, and the tests count only when the option is on | host devices: the option |
Networking and gamer services
| Type group | Public shape | Boundary at this snapshot | Owner page |
|---|---|---|---|
NetworkSession | Create, find, join; gamer collections; session state and events; host migration; SimulatedLatency and SimulatedPacketLoss | Only SystemLink puts bytes on a wire (through ENet, with LAN discovery); the other session types keep XNA's shape and simulate or refuse; no Xbox LIVE matchmaking and no Internet traversal; Find is empty on Emscripten; the two simulation properties act on application data (in FNA they are inert) | what each session type does |
LocalNetworkGamer, NetworkGamer | Identity, host and ready state, round-trip time, send and receive | Packet framing, peer identity, ordering and disconnect transitions are the parts that need two-process tests | delivery guarantees |
SignedInGamer and related types | Local identities, presence, privileges, achievements, leaderboards, Guide dialogs | Local, locally persisted or inert; no authentication, friends or remote account | three kinds of behaviour |
AvatarRenderer and related types | XNA's avatar API; opt-in SkinnedModelEXT real rendering | The base API is inert by fidelity; the extension is a separate, opt-in route; neither supplies Microsoft's avatar service or assets | two independent systems |
Storage
| Type | Public shape | Boundary at this snapshot | Owner page |
|---|---|---|---|
StorageDevice | Begin/End selector and container open, connection and capacity state, delete-container, application-root EXT | The Begin/End pairs complete before Begin returns; the root is a local directory chosen by a path chain, not a platform selector UI; 14 GoogleTest definitions cover refusals, containment and the isolated-storage coupling | storage internals: tests |
StorageContainer | Relative file and directory create, delete, enumerate, exists, open | Every path must stay inside the container (absolute paths, .. escapes and symlink escapes throw); wildcard queries support * and ? but have no direct test | storage: path containment |
Do not transfer evidence from one storage operation to all of them: the test population covers refusals far better than it covers round trips, disposal or glob matching.
sharp-runtime core types used everywhere
These come from the sibling library, read at sharp-runtime next @ 41b918c9; CNA does not pin it.
| Type group | Translation role | C++ reality | Owner page |
|---|---|---|---|
System::Object, type helpers | .NET-shaped base naming, equality, hash, string, runtime identity | Opt-in base; standard C++ objects and RTTI; no CLR object header, reflection universe, universal boxing or garbage collector | Object is opt-in |
Primitive aliases, String | C# primitive vocabulary mapped to fixed-width C++ types; string API vocabulary | An alias is not a CLR; text is UTF-8 and indices are bytes, so managed-string semantics need per-operation care | String is an API vocabulary |
TimeSpan, date and time | Tick-based durations, selected date and time operations | Value types with explicit arithmetic and validation; time-zone breadth is bounded | TimeSpan |
EventHandler<T> | Subscription, removal, clearing, raise | Combines the C# delegate and event roles explicitly; lifetime and thread safety stay contracts of the caller and the library | EventHandler |
| Collections, tasks, threads | Translation-friendly containers, tasks, cancellation, synchronisation | Fail-fast collections; a real but scoped task model; each API may be implemented, ignored or out of scope | tasks |
Stream, MemoryStream, readers and writers | Byte I/O, in-memory storage, binary and text helpers | Ownership, closed-state behaviour, encodings and exception types are per implementation | MemoryStream |
sharp-runtime's porting database is a set of workflow classifications, not a completion score. At 41b918c9 it has 16,207 task rows (1,087 ported, 14,980 ignored, 140 ignore) and 2,417 ticket rows; smaller totals quoted elsewhere belong to earlier revisions, and every total needs its query and revision (project records as evidence).
Language bindings: projections over a moving ABI
Eight binding projects consume CNA's experimental C ABI: C# (cna-cs), Java, TypeScript, Python, Rust, Swift, and, public since 2026-09-25, Go (cna-go) and Ruby (cna-ruby). They are separate repositories, not output of the CNA repository, and each reads its native library from a user-supplied path. In code every one targets the 0.21 ABI generation (Ruby also admits 0.7.0); several READMEs still say 0.20, which is stale. CNA snapshot 009d40f5 exports 0.29.0, and 0.28.0 and 0.29.0 were incompatible steps made after every binding's last commit. Five bindings refuse a 0.29.0 library by an exact-version rule, Go and Swift would nominally load it but were only ever qualified against 0.21.0, and Rust still declares a function 0.29.0 removed. A structurally complete language surface is therefore not a compatibility statement: a binding release has to regenerate or audit its declarations, admit the new version explicitly, rebuild its adapter and rerun its own host matrix. The per-binding commits, status words and loader rules are on C API: bindings boundary, and the maintainer's obligations on bindings architecture.
Applications as bounded consumers
Several public applications exercise CNA hard and are useful sources of observations, but each is evidence for its own revision and for the CNA revision it was built with, never for this snapshot by default. None is pinned by CNA, and CNA builds none of them.
| Repository (revision read) | What it is | What it exercises | How it obtains CNA; evidence boundary |
|---|---|---|---|
cna-car-simulator (04e4d104, 2026-09-24) | A passenger-car driving simulator in a fictional Czech landscape | The XNA surface under traffic, weather, day and night; deterministic lock-step captures for screenshots and tests | Sibling checkout (CARSIM_CNA_ROOT, default ../cna), no lock file. Its curated pictures are headless Mesa llvmpipe captures; its README also records eight deterministic scenes measured on an AMD Radeon 780M desktop in its current phase |
cna-city (267b79b9, 2026-09-04) | A procedural city with 100,000 simulated inhabitants | CNAEXT at scale: cascaded shadow maps, the HDR render pipeline with ACES, bloom and SSAO, instancing, culling | Sibling checkout of CNA's next under an older directory name, no lock file. Its README names the engine boundaries it met, for example that ClusteredForwardEffect could not carry many punctual lights and a texture set together at its CNA revision; at this snapshot ClusteredForwardEffect.hpp states the same boundary as a design choice (it binds no material textures, only base colour, metallic and roughness) |
cna-street (506cef1f, 2026-09-23) | A procedurally generated European inner-city street | The glTF metallic-roughness pipeline with licensed photogrammetry and CC0/CC-BY assets (licence and digest recorded per asset), skinned PBR people, audio, fourteen CPU-only test suites | dependencies.lock: CNA d4220380 (2026-09-06), easy-gl deda7a42, meta-gl 20c8b2dc; the lock exists "so a build failure can be attributed" |
cna-studio (0dd11d5b, 2026-09-24) | A visual development companion: project creation, assets, scenes, gizmos, build driver | Authoring on top of CNA's public API | Sibling checkout (CNA_STUDIO_CNA_ROOT). At version 1.0.0 (2026-09-23) its core workflow was declared complete and it entered maintenance mode. A game it authors is an ordinary CNA project that builds with Studio uninstalled, so Studio is not a CNA runtime dependency, and it is not CNA's diagnostics Inspector |
living-room-simulator (2bf3f56b, 2026-09-14) | An explorable 3D living room with weather and a solar clock | EasyGL (OPENGLES3) with CNAEXT lighting, reflections and cube maps; CPU-only tests of the clock, weather and bakers | dependencies.lock: CNA 1b3151f2 (2026-09-11), easy-gl deda7a42, meta-gl 20c8b2dc. Closed on 2026-09-14 with nine milestones; validated on Mesa llvmpipe only; the CNA limits it met are listed in its own findings file |
Their screenshots, tests and findings describe those revisions. They do not upgrade the renderer, platform or API evidence of snapshot 009d40f5, and a limitation one of them reports has to be re-checked at this snapshot before it is repeated; CNA's own confirmed defects are listed only through Known Issues. The wider repository map is on The CNA ecosystem: other repositories.
Reading this map safely
- Take the exact declaration from CNA's module-owned headers (
modules/*/include) or from sharp-runtime's headers at the revision you use, not from a row here. - Read the owner page for the semantics, then ask which evidence form it rests on: source read, test present, runtime observed, oracle compared, hardware observed (verification tiers).
- Check the host and renderer: many boundaries above are platform or renderer facts, not API facts.
- A type name shared by XNA, FNA, CNA and sharp-runtime establishes lineage. It does not by itself establish identical ownership, exceptions, threading, encoding, platform reach or behaviour.
Related pages
The same subject is explained at several altitudes. These are the neighbouring pages at each one.
- User guide
- XNA compatibility: presence versus behaviour · Input guide · Audio guide · Storage guide · C API: bindings boundary
- Internals
- Storage module internals · Net module internals
- Reference
- CMake option index