Sector User Data - pk-hack/CoilSnake GitHub Wiki

This is a system added in EBME 1.4.0 that lets you attach custom data to sectors. Then, you can write some code to access it and do things based on the player's location in the world. What exactly that is: up to you!

In Sector mode, press the "Show User Data Menu" button on the sidebar to reveal the interface.

  1. Press this to close the menu again
  2. After you've exported some data, you can import it later to edit again.
  3. After you've added some data, you can export it to a CCScript file.
  4. Press this to add a new data field
  5. Press this to delete the selected data field
  6. Tracks how much space the data is taking up. This is the size of each field multiplied by the amount of sectors. This cannot exceed 65536 bytes.
  7. Data fields show up here once you add some. The first column is the data value and the second is the data type.

Adding user data fields

Press the "+" button (number 4 in the diagram above) to add a field of data. Every sector will get this field as a new attribute.

The name must be something that's a valid name in CCScript (ie. alphanumerical, underscores, can't start with a number). There are several data types to choose from, which are different sizes and imply different purposes:

Data types

Bitfield

Eight true/false values packed into a single byte. Good for having many boolean properties in a compact space.

Int8, Int16, Int24, and Int32

Unsigned integers. Respectively, these take up one, two, three, and four bytes, and can store values 0-255, 0-65535, 0-16777215, and 0-4294967295. You should choose whichever one is the smallest that fits the range you're expecting to need.

SignedInt8, SignedInt16, SignedInt24, and SignedInt32

Signed integers. Respectively, they take up one, two, three, and four bytes, and can store values -128-127, -32768-32767, -8388608-8388607, and -2147483648-2147483647. You should choose whichever one is the smallest that fits the range you're expecting to need.

Identifier8, Identifier16, Identifier24, and Identifier32

Any valid CCScript identifier, such as a definition or label. Respectively, they take up one, two, three, and four bytes. Labels at minimum need three bytes, but four bytes makes reading a table of them slightly more efficient at the cost of more ROM used. It is also useful to use this to store a defined value. Data is truncated/expanded by the CCScript compiler according to its own behaviour.

Editing user data fields

After you've added some fields (or imported data), they'll show up in the table (number 7 on the diagram). Select a sector (or multiple sectors), and then you can double-click the cells to edit the data for the selected sector(s). You can't edit the data type here.

This data will be copied and pasted alongside other sector attributes, and everything you do can be undone/redone.

Exporting/importing user data

The data isn't added directly to the sector table. Instead, it'll be saved to an auxiliary table stored in a CCScript file. You shouldn't edit this file by hand, because EBME can import it again later for further edits. To export, press the "Export data" button (number 3). To import, press the "Import data" button (number 2). When importing, you'll also get a preview of the data structure.

Using the user data

If you open the exported CCScript file, you'll see a few definitions, followed by the data format macro and all of the data itself. The first set of definitions are structure offsets. The SIZEOF_SECTORUSERDATA definition is the size of one user data structure frame. You don't need to worry about the macro. The label at the start of the table is the base of the data. Therefore, to access a given field of sector user data in your ASM code, the formula is SECTORUSERDATA + (sectorID * SIZEOF_SECTORUSERDATA) + SECTORUSERDATA_my_field. If you have the player's coordinates in pixels, you can get a sector's ID from them by doing ((y>>2) & 0xFFE0) + (x>>8). Respecting the data type is your responsibility.