> For the complete documentation index, see [llms.txt](https://g3m.gitbook.io/g3mwiki/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://g3m.gitbook.io/g3mwiki/main/g3mlib/apis-and-examples/data-files.md).

# DATA files

`G3MLib.DataFile.GameMakerData` contains typed resource collections such as Rooms, Sprites, Sounds, GameObjects, Code, and Strings. `GeneralInfo` describes the game and resource format. Availability depends on the chunks present in the file.

## Read

```csharp
using G3MLib.DataFile;

using var input = File.OpenRead("original.win");
using var data = GameMakerIO.Read(input,
	warningHandler: (warning, isImportant) => Console.Error.WriteLine(warning));
```

`GameMakerIO.Read` accepts a readable stream, optional warning and message callbacks, and `onlyGeneralInfo`. The latter requests a partial metadata read; do not use that partial model to modify or rewrite a full game file.

The warning callback receives the message and an `isImportant` flag. Keep both available if your interface distinguishes warnings that require attention from other reader messages.

Retain warning information. Some unusual or unsupported files can produce warnings or throw during parsing. Suppressing a warning does not establish that a later write is valid.

## Edit and write

```csharp
using G3MLib.DataFile;
using G3MLib.Modding.Patching;

using var input = File.OpenRead("original.win");
using var data = GameMakerIO.Read(input);
if (data.Rooms is null || data.Rooms.Count == 0)
{
	throw new InvalidDataException("Expected at least one room.");
}
data.Rooms[0].Width += 16;
input.Dispose();
PatchInputService.WriteDataFile(data, "output/edited.win", "original.win");
```

WriteDataFile writes and validates the output and handles required external audio groups from the output/source locations. Keep the companion files with the DATA result when copying it into a test installation.

`GameMakerIO.Write(stream, data, messageHandler)` provides raw serialization when the host manages the stream and companion files itself. It does not package a complete game or mod.

`PatchInputService.CopyDataFile(source, output)` copies DATA and its external audio groups. It is preferable to copying only the main DATA file for a workflow that needs those groups.

## Resource references

Resource objects refer to other resources and shared strings. Reordering, deleting, or creating collections can require more than assigning a numeric field. Use resource/project import or patch services for changes with companion files and references.

`data["Rooms"]` provides a resource collection by its property name. Unknown names throw; typed properties are preferable when the resource type is known at compile time.

Dispose loaded DATA after use. Do not modify the same model concurrently from several operations. Reopen the result with GameMakerIO and test with the matching game runner before distributing it.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://g3m.gitbook.io/g3mwiki/main/g3mlib/apis-and-examples/data-files.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.