A boundary we can keep stable.

What exists now Binary SDK terms apply

Every symbol and signature is documented publicly. Commercial use of the prebuilt GameReader library at or above EUR 1 trillion annual revenue needs an enterprise license; implementation source needs a separate paid agreement. See API access and licensing.

The CMake package exports AmoosedWeb::GameReaderC as a shared library. Its amw_preview_* functions parse a game catalogue, open hosted or externally keyed Windows and Linux sites, list indexed paths, and download verified byte-addressable, PNG low-bit, AWF1/AWF2 sparse-frame, and WAV tone resources. Plain C and .NET 10 callers run against Windows and Linux libraries and local carrier fixtures. The prefix says exactly what it is: a changeable preview, not a 1.0 compatibility promise.

The proposed general Reader 1.0 contract has a C header draft and a design explanation. The draft is for review only: no shipped library exports its amw1_ names, and its values are not frozen. Game and compiler APIs are deliberately outside that draft.

Start with the plain C Reader quickstart, or download the complete source example. It checks revision and capabilities, opens a hosted index or an externally keyed index from a local .amwkey or packed ICO file, selects the entry or a named resource, and saves verified bytes without overwriting an existing file. Use native-c-site --external CREDENTIAL_FILE ORIGIN [RESOURCE_PATH] ABSOLUTE_OUTPUT_PATH for the external edition; the file is read locally and credential bytes are never passed as command arguments. For a protected resource, add --member MEMBER_FILE before the origin and name the resource path. The example parses the local .amwmember file, checks its edition ID against the verified index, and clears its key bytes after use. The Linux x64 review ZIP compiles this example against its extracted prebuilt library and tests exact external and protected recovery from local fixtures, including refusal to overwrite an existing output.

find_package(AmoosedWebGameReader 0.28 CONFIG REQUIRED)
target_link_libraries(your_tool PRIVATE AmoosedWeb::GameReaderC)

The header is AmoosedWeb/PreviewC.h in the local CMake install. It declares fixed-width integer arguments and opaque catalogue, site, and game handles.

Complete preview symbol set

PreviewC.h gives the exact signatures, constants, field IDs, and calling convention. The machine-readable ABI inventory records the preview revision, capability bit values, public header hash, and exported symbol names for tooling. It is generated from the same header shipped in the SDK. The current exported API is:

Status codes include NOT_FOUND for an absent indexed path or game item, INVALID_STATE for an unready or consumed handle, STALE_REVISION for a rejected game rollback, BAD_FORMAT for malformed catalogue data, plus authentication, verification, network, output, cancellation, and unsupported failures. Revision 16 retains the old numeric INVALID_DATA and READ_ERROR definitions only for preview compatibility; callers should use the precise statuses. The header defines the numeric values and the catalogue and resource field selectors. A delayed-carrier .NET P/Invoke test cancels an active download and checks that no final or staging file remains. Prepare a single-use operation before dispatching a synchronous site or game call, cancel it from another thread, and release it after the call returns. The older convenience open calls still return a handle only after opening completes. These preview values may change before 1.0.

Standalone WAV from plain C Public API documentation

Revision 14 adds amw_preview_audio_decode_file for one self-contained AWA1 WAV. It needs the original WAV bytes and the separate 32-byte media key. It does not need a website index or member key. Check AMW_PREVIEW_CAP_AUDIO_FILE, then call once with a null output and zero capacity to authenticate and query the plaintext length. Allocate that many bytes and call again to copy the authenticated result. The 64 MiB WAV input bound and 4,068-byte plaintext profile apply; this local call is synchronous and has no cancellation handle.

uint64_t required = 0;
int32_t status = amw_preview_audio_decode_file(wav, wav_length,
    media_key, 32, NULL, 0, &required, error, sizeof(error));
if (status != AMW_PREVIEW_OK) { /* handle typed status */ }
/* Allocate required bytes, then call again with that buffer and capacity. */

Download the complete plain-C example, also included in both source-free review SDK ZIPs. It reads the media key from a local hex file, authenticates the WAV, and creates the requested output without overwriting an existing file. Pass a trusted local output path; the key stays out of command arguments.

A short buffer returns BUFFER_TOO_SMALL and leaves it untouched. Wrong keys return AUTHENTICATION_FAILED; malformed WAV and damaged packets have separate status categories. No recovered bytes are released before full verification. Keep the key out of command arguments, pipeline strings, and logs. An optional GStreamer element can use this C boundary later; no GStreamer plugin is shipped today.

Capability negotiation Public API documentation

Call amw_preview_capabilities after checking the preview revision, then require the bits for the operations your product uses. The mask describes compiled support in the loaded binary; it is not a license, site permission, or credential. Unknown bits may be ignored. Windows x64 and Linux x64 preview builds report catalogue, site, game, cancellation, and media capabilities. Query the actual loaded binary; other platforms are not yet packaged.

uint64_t available = 0;
uint64_t required = AMW_PREVIEW_CAP_HOSTED_INDEX |
                    AMW_PREVIEW_CAP_BYTE_CARRIERS;
if (amw_preview_abi_revision() != AMW_PREVIEW_ABI_REVISION ||
    amw_preview_capabilities(&available) != AMW_PREVIEW_OK ||
    (available & required) != required) {
    /* Disable the integration or report unsupported runtime. */
}

The future 1.0 amw1_query will use a separate stable major/minor contract. This preview mask does not freeze those future bit numbers.

Verified bytes in memory

amw_preview_site_read_memory copies a resource into caller-owned memory after all carrier and resource hashes pass. Pass NULL with capacity zero to query its plaintext length from the already verified index; this query does not download or verify the resource bytes. A short buffer returns BUFFER_TOO_SMALL, reports the required length, and leaves the buffer unchanged. Other failures leave both the buffer unchanged and the reported length zero. The limit is AMW_PREVIEW_MEMORY_LIMIT (64 MiB); use the file download for larger resources. The plain-C memory example checks capabilities, queries the length, allocates a bounded caller buffer, and uses the bytes only after a successful verified read. Pass a prepared operation to amw_preview_site_read_memory_operation when another thread must be able to cancel the read. The standalone .NET preview facade exposes this operation as ReadBytesAsync.

Text and binary input rules

Every direct C text argument uses an explicit byte length, strict UTF-8, and no embedded NUL. Invalid text returns INVALID_ARGUMENT before network or filesystem I/O. Catalogue JSON with malformed UTF-8 returns BAD_FORMAT. External-index credentials and 32-byte member keys remain binary inputs; they are not decoded as text at the ABI boundary. A valid multibyte UTF-8 path is accepted subject to the normal path and resource checks.

Output values on failure

The preview clears supplied handle and numeric outputs before returning an error: an unsuccessful handle is NULL, and a byte count, revision, item count, or resource length is zero. Caller-owned text buffers remain unchanged on a failed field query. A valid length query or BUFFER_TOO_SMALL sets required to the UTF-8 byte count without the terminating NUL; other failures set it to zero. Diagnostic error buffers are separate and may contain bounded text. Check the status before using any output.

Cancellation and operation lifetime

Prepare one operation before dispatching a synchronous site or game call to a worker. A different thread may cancel it. Join the worker before releasing the operation or its site/game handle. Each operation is single-use; create another for the next call. Calls on the same site or game handle remain serialized.

amw_preview_operation *operation = NULL;
if (amw_preview_operation_prepare(&operation) != AMW_PREVIEW_OK) return;
/* A worker calls amw_preview_site_download_operation(site, operation, ...).
   Another thread may call amw_preview_operation_cancel(operation).
   Join the worker before releasing either handle. */
amw_preview_operation_release(operation);

A cancelled operation returns CANCELLED. A later operation on the same site or game can proceed; the legacy handle-level cancel calls remain in the preview for existing consumers. The public header lists every operation variant and its exact arguments.

Failure status reference Public API documentation

The status value is machine-readable. The caller-owned error buffer provides diagnostic detail and may change between preview releases. Check the status before using any output handle or file.

These categories describe the current Windows and Linux preview and can be refined before the 1.0 ABI freeze. The licensed SDK uses the same publicly documented status contract.

Call and ownership rules

amw_preview_catalogue *catalogue = NULL;
char error[128] = {0};
int32_t status = amw_preview_catalogue_parse(
    json_bytes, json_length, &catalogue, error, sizeof(error));
if (status == AMW_PREVIEW_OK) {
    uint64_t count = 0;
    amw_preview_catalogue_item_count(catalogue, &count);
    /* Query a field's length, then copy into your own buffer. */
    amw_preview_catalogue_release(catalogue);
}

The caller owns input JSON, error text, and output buffers. The library owns the opaque handle until amw_preview_catalogue_release. Strings are copied, so no pointer into C++ object storage escapes. A too-small output buffer is left untouched and the required length is returned. Site and game handles also remain caller-owned; serialize their operations, call cancel from another thread if needed, and release only after active calls return. A .NET 10 interop example exercises these rules and hosted/external downloads with the installed DLL; its setup notes and project file are available separately.

Proposed 1.0 contract

The first stable C boundary is for the general Reader: verified hosted and external indexes, resource metadata, public and member memory reads and downloads, cancellation, and transactional output across every carrier mode claimed by a platform package. Game catalogue and Unreal operations remain optional preview layers until their own parity gate passes. The native compiler needs a separate stable contract after compiler parity. The symbol namespace, calling convention, fixed status codes, handle and operation lifetimes, and packaged binaries must be specified and tested before the Reader's 1.0 freeze.

We propose amw1_ for the stable Reader major and a separate future amwc1_ namespace for the compiler, with independent capability queries and immutable baselines. A 1.x ABI adds functions without changing existing signatures; a breaking ABI uses a new major namespace. The revision-16 preview now distinguishes NOT_FOUND, INVALID_STATE, malformed format, and transport failures. A failed local SHA-256 or AES-GCM provider is classified separately from changed carrier bytes or a rejected authentication tag in the built-in Windows and Linux Readers. These names, values, and behavior still need a stable 1.0 freeze gate. The complete proposal and release gate are in the 1.0 design.

Compatibility contract before 1.0

Public API documentation The current source DLL reports preview revision 16. Its plain-C callback fixture has passed on Windows. The local Windows .NET and Node review packages use revision 16. The Linux and Unreal review packages still target revision 14 and cannot use this DLL. Preview consumers check the exact revision because signatures may change. The local SDK packaging gate compares the Windows x64 DLL export table and the Linux x86_64 ELF export table with every declaration in the public C header; missing or undocumented symbols fail the package build.

For 1.0, we propose a permanent amw1_ symbol namespace and a major/minor capability query. A 1.x library would retain existing signatures, status values, ownership, and calling conventions; new functions or optional capabilities would be additive. A breaking change would use a new major namespace. This is a design rule, not a claim that the current preview already provides 1.0 compatibility. Read the proposed 1.0 contract for version, ownership, cancellation, and error rules. The release gate lists the parity and platform checks still required.

Reader migration

The published .NET Reader still invokes the native amw CLI, and the Unreal plugin now has a locally tested Win64 hosted-catalogue and public-item path. This preview proves cross-language calling, ownership, and verified Windows downloads. A clean Linux .NET consumer now lists a hosted index and recovers exact bytes. Linux plain-C fixtures cover a hosted public download, an external index, rejection of member data with an absent or incorrect key, and exact member recovery. Linux C++ fixtures also cover PNG low-bit, AWF1/AWF2 sparse-frame, and WAV tone carriers. This does not yet justify changing the published Reader or Unreal plugin. See the capability matrix for the remaining gates.