Scripting API

Scripting API

ImportSettings

Record struct in Abyss.Core, from Abyss.Core.

How one file should be read, as sixteen numbers.

public readonly record struct ImportSettings

Remarks

These belong to the file, not to whoever is loading it. A glTF file records its geometry with +Z forward; a PNG holds either a color somebody chose or a number a shader reads, and nothing in the file says which. Each of those has one right answer, the same every time that file is loaded — by a game, by the editor, or by a scene somebody opens in two years — so it is written down beside the file rather than passed at each call site.

Zero means nothing was said, in every field, and ImportSettings.NothingSaid is the value of a file nobody has configured. For a model that is the load the engine has always made, and an import with the defaults — the file's scale, the index size each mesh needs, its own normals and tangents, each made where it has none, and 60° where normals are calculated. For an image it is the defaults every texture nobody configured is imported with — mipmaps made with a box filter, no larger than ImportSettings.DefaultMaxSize, filtered bilinearly, tiling and compressed at normal quality — which the engine fills in, so a sidecar holds only what somebody chose.

Laid out to match the engine's own ImportSettings: sixteen uints in this order, sixty-four bytes. It crosses the boundary by value like a MaterialSpec does, and for the same reason — Bevy's own loader settings are Rust types full of options and strings, and none of that is something C# can write.

Constructors

ImportSettings

public ImportSettings(ImportAxes Axes, ImportColor Color, ImportFilter Filter, ImportWrap Wrap, ImportMipmaps Mipmaps = Default, ImportMipFilter MipFilter = Default, uint MaxSize = 0, uint Aniso = 0, ImportTextureType TextureType = Default, ImportCompression Compression = Default, uint Scale = 0, ImportIndexFormat IndexFormat = Auto, ImportNormals Normals = Default, uint SmoothingAngle = 0, ImportTangents Tangents = Default, uint PreserveHierarchy = 0)

How one file should be read, as sixteen numbers.

Parameters

  • Axes: What to do about a model's axes. Models only.
  • Color: What an image's numbers mean. Images only.
  • Filter: How an image is sampled. Images only.
  • Wrap: What an image does past its edges. Images only.
  • Mipmaps: Whether an imported image has its mipmaps. Images only.
  • MipFilter: How each mipmap is made. Images only.
  • MaxSize: The longest side an imported image may have, a power of two from 32 to 8192, or zero for ImportSettings.DefaultMaxSize. Images only.
  • Aniso: How many samples a slanted surface may take, 1 to 16, or zero for one. Images only.
  • TextureType: What an image is for. Images only.
  • Compression: Whether an imported image is block-compressed, and how well. Images only.
  • Scale: The Scale Factor a model's positions are multiplied by, as the bits of a float greater than zero, or zero for one; see ImportSettings.ScaleFactor. Models only.
  • IndexFormat: How big each number of an imported mesh's index buffer is. Models only.
  • Normals: Where an imported mesh's normals come from. Models only.
  • SmoothingAngle: The Smoothing Angle normals are calculated with, one more than its whole degrees so that zero can mean 60°; see ImportSettings.SmoothingDegrees. Models only.
  • Tangents: Where an imported mesh's tangents come from. Models only.
  • PreserveHierarchy: Whether a model's prefab keeps a root of its own, named after its file, above the one node at the top of the file — one — or makes that node its root — zero; see ImportSettings.KeepsHierarchy. Models only, and read by the prefab rather than by the import of its meshes.

These belong to the file, not to whoever is loading it. A glTF file records its geometry with +Z forward; a PNG holds either a color somebody chose or a number a shader reads, and nothing in the file says which. Each of those has one right answer, the same every time that file is loaded — by a game, by the editor, or by a scene somebody opens in two years — so it is written down beside the file rather than passed at each call site.

Zero means nothing was said, in every field, and ImportSettings.NothingSaid is the value of a file nobody has configured. For a model that is the load the engine has always made, and an import with the defaults — the file's scale, the index size each mesh needs, its own normals and tangents, each made where it has none, and 60° where normals are calculated. For an image it is the defaults every texture nobody configured is imported with — mipmaps made with a box filter, no larger than ImportSettings.DefaultMaxSize, filtered bilinearly, tiling and compressed at normal quality — which the engine fills in, so a sidecar holds only what somebody chose.

Laid out to match the engine's own ImportSettings: sixteen uints in this order, sixty-four bytes. It crosses the boundary by value like a MaterialSpec does, and for the same reason — Bevy's own loader settings are Rust types full of options and strings, and none of that is something C# can write.

Properties

Axes

public ImportAxes Axes { get; init; }

What to do about a model's axes. Models only.

Color

public ImportColor Color { get; init; }

What an image's numbers mean. Images only.

Filter

public ImportFilter Filter { get; init; }

How an image is sampled. Images only.

Wrap

public ImportWrap Wrap { get; init; }

What an image does past its edges. Images only.

Mipmaps

public ImportMipmaps Mipmaps { get; init; }

Whether an imported image has its mipmaps. Images only.

MipFilter

public ImportMipFilter MipFilter { get; init; }

How each mipmap is made. Images only.

MaxSize

public uint MaxSize { get; init; }

The longest side an imported image may have, a power of two from 32 to 8192, or zero for ImportSettings.DefaultMaxSize. Images only.

Aniso

public uint Aniso { get; init; }

How many samples a slanted surface may take, 1 to 16, or zero for one. Images only.

TextureType

public ImportTextureType TextureType { get; init; }

What an image is for. Images only.

Compression

public ImportCompression Compression { get; init; }

Whether an imported image is block-compressed, and how well. Images only.

Scale

public uint Scale { get; init; }

The Scale Factor a model's positions are multiplied by, as the bits of a float greater than zero, or zero for one; see ImportSettings.ScaleFactor. Models only.

IndexFormat

public ImportIndexFormat IndexFormat { get; init; }

How big each number of an imported mesh's index buffer is. Models only.

Normals

public ImportNormals Normals { get; init; }

Where an imported mesh's normals come from. Models only.

SmoothingAngle

public uint SmoothingAngle { get; init; }

The Smoothing Angle normals are calculated with, one more than its whole degrees so that zero can mean 60°; see ImportSettings.SmoothingDegrees. Models only.

Tangents

public ImportTangents Tangents { get; init; }

Where an imported mesh's tangents come from. Models only.

PreserveHierarchy

public uint PreserveHierarchy { get; init; }

Whether a model's prefab keeps a root of its own, named after its file, above the one node at the top of the file — one — or makes that node its root — zero; see ImportSettings.KeepsHierarchy. Models only, and read by the prefab rather than by the import of its meshes.

ScaleFactor

public float ScaleFactor { get; }

What a model's positions are multiplied by, what was not said filled in.

SmoothingDegrees

public uint SmoothingDegrees { get; }

The angle, in whole degrees, normals are smoothed up to, what was not said filled in.

MaxSizes

public static IReadOnlyList<uint> MaxSizes { get; }

The Max Sizes a texture can be imported at, smallest first.

NothingSaid

public static ImportSettings NothingSaid { get; }

The settings of a file nobody has configured.

SaysNothing

public bool SaysNothing { get; }

Whether these settings say anything at all.

KeepsHierarchy

public bool KeepsHierarchy { get; }

Whether a model's prefab keeps a root of its own above the one node at the top of its file.

TouchesModels

public bool TouchesModels { get; }

Whether anything here has anything to do with a model.

TouchesImages

public bool TouchesImages { get; }

Whether anything here has anything to do with an image.

Srgb

public bool Srgb { get; }

Whether an imported image's colors are sRGB-encoded: everything but numbers.

A normal map and a single channel are numbers whatever their color setting says.

HasMipmaps

public bool HasMipmaps { get; }

Whether an imported image has its mipmaps.

LongestSide

public uint LongestSide { get; }

The longest side an imported image may have, what was not said filled in.

IsCompressed

public bool IsCompressed { get; }

Whether an imported image is block-compressed.

Methods

ScaleOf

public static uint ScaleOf(float factor)

A Scale Factor as ImportSettings.Scale holds it: one is nothing said.

Parameters

  • factor

SmoothingOf

public static uint SmoothingOf(uint degrees)

A Smoothing Angle in whole degrees as ImportSettings.SmoothingAngle holds it: 60° is nothing said.

Parameters

  • degrees

MeshSettings

public ImportSettings MeshSettings()

The settings that change a model's imported meshes, what was said the same as what was not written the same, so two that differ only in how they say it are one import.

The angle is one of them unless normals are left out: a mesh whose file has none has them calculated with it when they are imported, too.

PixelSettings

public ImportSettings PixelSettings()

The settings that change an imported image's pixels, so two that differ only in how it is filtered are one import, drawn two ways.

The wrap is one of them while there are mipmaps: each is made wrapping at its edges as the texture does, so a tiling texture's smaller levels still tile.

A normal map is one once compressed, two channels where color as numbers is three; and the compression only where it chooses another format — low quality is normal quality for now, and high quality is BC7 for color alone.

Constants

DefaultMaxSize

public const uint DefaultMaxSize = 2048

The longest side an image is imported at when nothing was said.

DefaultSmoothingDegrees

public const uint DefaultSmoothingDegrees = 60

The angle normals are smoothed up to when nothing was said.