[RFC] Adding info to generate wiki tables by Suzanna-Linn · Pull Request #160 · secondlife/lsl-definitions

Suzanna-Linn · 2026-06-22T13:00:47Z

This is a draft PR only for comments, with a few changes as examples, and is not intended to be merged.

The objective is to add enough information to be able to generate tables of constants on a Docs page, similar to how they are in the SL Wiki.

Once we have decided on the format, I will open a new PR with all the changes.

It has things in common with:

This PR uses a slightly different approach than #113 to show another point of view, but it can be made compatible with it.

This PR uses the same approach as #143.

Please comment...

Suzanna-Linn · 2026-06-22T13:31:48Z

  PSYS_PART_FLAGS:
    member-of: [ParticleParam]
    tooltip: Integer bitfield parameter specifying the simulation flags for emitted
      particles. Multiple flags can be combined using bitwise OR (|).
    type: integer
    value: 0
+    value-type: integer
+    enum : ParticleFlag


"value-type" is the type of the parameter.

"enum" is the category of constants of the parameter.

The Docs need to know the type of enum: "enum" or "flag".
This is obtained from "type" in the category definition:

is "flag" when "type" is "flag", else

is "enum"

#113 uses 3 fields instead of "enum": "enum-semantics", "param-semantics", "param-get-semantics".

The conversion is:

is "enum-semantics" when the enum has no constants with parameters, else

is "param-get-semantics" when is a function return or is a function argument and the same than the function return, else

is "param-semantics"

"value-type" is the same than #143.

Types in "value-type" are:

integer

float

string

vector

rotation

boolean

asset

key

string-csv

string-map

string-multi

(edited to add "string-multi")

new one for the list string-multi on the lua side looks like a string array... (just like string-csv)

I have updated it to add "string-multi".

By the way, would it be interesting to use these datatypes in arguments, returns, and constants?

"boolean" instead of "integer" + "bool-semantics".

"asset" instead of "string" + "asset-semantics".

a possible new datatype "index" instead of "integer" + "index-semantics".

I'm planning to submit a PR consolidating how rulesets and the rest of the file use types and the type-semantics flags. It would allow marking functions and arguments as boolean, asset, index without a bunch of semantics fields.

I keep thinking about the value-type parameter, and how to relate it to multi value parameters.
It seems to me this could be either a simple type or, if there are multiple values expected for a parameter, an array of types.

I'm considering ways to simplify the builder type rulesets... but that is perhaps another discussion.

I have an idea in mind for simplifying all the types, but I was kinda waiting on this and #113 to be merged first. It sounds like maybe I should submit it sooner rather than later so we can discuss it

I leave the type-semantics improvements to Tapple

I published my type-semantics improvements idea: Reusable LSL type semantics #164

Suzanna-Linn · 2026-06-22T13:47:45Z

  SKY_GLOW:
    member-of: [EnvironmentParamReadOnly, EnvironmentParam]
    tooltip: "Environmental setting for sun and moon glow parameters: size and focus."
    type: integer
    value: 6
+    values:
+    - glow_size:
+        value-type: float
+        range: [0.2, 40]
+    - glow_focus:
+        value-type: float
+        range: [-10, 10]  


"values" is an array of parameters, when there is more than one

"range" is a [ start, end ] array with the range of values

Suzanna-Linn · 2026-06-22T13:51:11Z

  CAMERA_DISTANCE:
    member-of: [CameraParam]
    tooltip: Sets how far away the camera wants to be from its target.
    type: integer
    value: 7
+    values:
+    - meters
+        value-type: float
+        range: [0.5, 50]
+        default: 3.0


"default" is the default value of the parameter

"values" is used with only one parameter if it has an informative name

#113 uses "enum", "param-dict" and "param-list" in the "type" of the categories of constants. This PR doesn't use them.

The conversion is:

is "enum" when there is no "value-type", else

is "param-dict when there is "value-type" or "values" with only one parameter, else

is "param-list"

I don't have a strong opinion on which way to do it. I decided to seperate the enum types into enum, param-dict, and param-list in the PR so that:

A documentation generator would know up front which format to use

The generator code in lsl-definitions could validate that constants have the correct number of arguments for that type (0, 1, >1, respectively).

However, both you and harold don't seem to care for enums to have that info embedded in type (see #113 (comment)). So I can remove them from my PR

Suzanna-Linn · 2026-06-22T13:58:37Z

  OBJECT_ATTACHED_POINT:
    member-of: [ObjectDetailsParam]
    tooltip: Flag used with llGetObjectDetails. Returns the integer attachment point
      matching an ATTACH_* constant, or 0 if the target is not an attachment
      (e.g., an avatar or unattached object).
    type: integer
    value: 19
+    value-type: integer
+    open-enum: AttachPoint
+    details: 'local: llGetAttached; max chars: 11'


"open-enum" is an enum that has other possible values (in this case a 0)

"details" is a generic field to place all the other info in the SL Wiki table

#113 uses "other-values" for enums that can have other values, but it doesn't work in this case:

OBJECT_ATTACHED_POINT has AttachPoint and 0

llAttachToAvatar() has AttachPoint only.

It would need a new constant for 0 and a new category with it.

Definitely make a PR just for this. Proposals for new constants need strong justification and extra scrutiny. See previous accepted examples:

Add LAND_BRUSH_* constants #106

Add missing constant SIT_OK #114

Add missing constant ENV_OK #115

No, no, I'm not suggesting to add a new constant, just commenting to show that alternatives are complicate.
I'm going with "open-enum" for now.

Suzanna-Linn · 2026-06-22T14:08:15Z

  PRIM_BUMP_SHINY:
    member-of: [PrimParam]
    tooltip: Prim parameter used to get or set both the shininess and bump mapping
      settings of a face.
    type: integer
    value: 19
+    values:
+    - face
+        value-type:integer
+        get-arg: true
+    - shiny:
+        value-type:integer
+        enum: PrimShiny
+    - bump:
+        value-type:integer
+        enum: PrimBump


"get-arg" is a boolean indicating that the parameter, when the constant is used in get functions, is used in the function argument and not in the function return.

The Docs can identify when a category of constants is used as get in a function argument because the function return value has the same category.

It's only used when true, it's false by default.

If memory serves, the number of parameters that can be set but not gotten are very few.
May I suggest:

access: read -- read access, no write access: write -- write access, no read

default would be access: read-write

This looks good: "access: write" instead of "get-arg: true".

"face" in the Prim Param family is the only value in constants used in parameter lists that is "write" only, all others values change depending on how the constants are used.

The constants in parameter lists that are only used for "write" or "read" are these ones:
https://suzanna-linn.github.io/slua/wiki-read-write-constants.html

Do we add "access:" to these constants?

@gwigz did this somewhat differently by putting the write and the read arguments into different list fields. Not sure which approach I prefer: https://github.com/gwigz/slua/blob/bb02dbe8d7b927d0b67deed9eb1cc7e903c67c03/refs/typed-list-params.json#L1224-L1252

Just to point out the obvious, the generators can also use the access field when building definitions and wrappers.

Gwigz duplicates the constants when they are used for read and write.

To fit it in our structure we could use two sections in each constant for its values: "write" and "read".

It works but I think that it's longer.

Another possibility with "access":

read

write

read/write

arg

"read" and "write" would be the values that are stored as data values somewhere, many of them in the prim.

In this case "face" would be "access: arg".

Suzanna-Linn · 2026-06-22T14:09:44Z

  PRIM_TYPE_SCULPT:
    member-of: [PrimType]
    tooltip: Shape parameter for PRIM_TYPE used to define the prim as a sculpted
      prim (sculpty) or mesh of a specific type.
    type: integer
    value: 7
+    values:
+    - map
+        value-type: asset
+    - type
+        value-type: integer
+        enum: [PrimTypeSculptType,PrimTypeSculptFlag]


"enum" is an array of categories of constants when two are used together

#113 uses groups of categories, PrimTypeSculpt in this case, it works too.

The two categories can be obtained from "enum" and "flag" in PrimTypeSculpt

Suzanna-Linn · 2026-06-22T14:17:09Z

  llReturnObjectsByOwner:
    arguments:
    - owner:
        tooltip: UUID of the avatar or group whose objects will be returned.
        type: key
    - scope:
        tooltip: OBJECT_RETURN_* scope flag (such as OBJECT_RETURN_PARCEL,
          OBJECT_RETURN_PARCEL_OWNER, or OBJECT_RETURN_REGION).
        type: integer
+        enum: ReturnObjectsScope
    energy: 10.0
    func-id: 521
    return: integer
+    enum: ReturnObjectsError


An example of "enum" in a function

Suzanna-Linn · 2026-06-22T14:18:42Z

  llSetLinkColor:
    arguments:
    - link:
        tooltip: Link number (1 for root, >1 for children) or a LINK_* flag.
        type: integer
+        open-enum: Links
    - color:
        tooltip: Color vector in RGB <R, G, B> (values from 0.0 to 1.0).
        type: vector
    - face:
        tooltip: Face number or ALL_SIDES.
        type: integer
+        open-enum: Faces
    energy: 10.0
    func-id: 140
    return: void


An example of "open-enum" in a function

#113 has "other-values" in these two enums.

In this case "enum" could be used instead of "open-enum" since the enum is already defined as open.

Suzanna-Linn · 2026-06-22T14:22:02Z

  llSensor:
    arguments:
    - name:
        tooltip: Specific object or avatar name to filter for (or empty string for
          no filter).
        type: string
    - id:
        tooltip: UUID of the group, avatar, or object to filter by (or NULL_KEY for
          no filter).
        type: key
    - type:
        tooltip: Integer bitfield type mask containing AGENT, AGENT_BY_LEGACY_NAME,
          AGENT_BY_USERNAME, ACTIVE, PASSIVE, or SCRIPTED (0 for no filter).
        type: integer
+        enum: DetectType
    - radius:
        tooltip: Maximum distance in meters to scan (range [0.0, 96.0]).
        type: float
+        range: [0.0, 96.0]
    - arc:
        tooltip: Maximum angle in radians relative to the local X-axis to scan
          (range [0.0, PI]).
        type: float
+        range: [0.0, PI]
    energy: 10.0
    func-id: 28
    return: void


An example of "range" in a function

Suzanna-Linn · 2026-06-22T14:33:41Z

  game_control:
    arguments:
    - id:
        tooltip: UUID of the avatar supplying controller input.
        type: key
    - button_levels:
        tooltip: A 32-bit mask representing the buttons currently held down on the
          controller.
        type: integer
+        enum: GameControlButton
    - axes:
        tooltip: A list of six float values in the range [-1.0, 1.0] representing
          controller axes.
        type: list
        slua-type: "{number}"
+        used-enum: GameControlAxis
    tooltip: Triggered when a compatible viewer sends game controller input changes
      for the avatar specified by id. Only triggers for scripts in attachments
      or seats.
    categories:
      - avatar
      - input


"used-enum" is when an enum is used with the a function return but not in a regular way.

Regular ways are, when the return is:

a value: the value is in the enum

a list: the values are the parameter values of the constants in the enum

In this case the enum has the names of the indexes in the returned list.

I'm not sure if this is enough difference to have a new field, or it could be just "enum", since the use of it should be explained in the tooltips.

#113 has no enum in this field, but Docs need the enum associated with it in some way to show the table.

oh dear. These enums are used as list/table indexes. That will only work correctly LSL, not Lua. I wonder how insane it would be to have these constants have different values in LSL and Lua. It's unprecedented. Definitely needs it's own PR to discuss this, and a canny issue, and maybe bringing up on discord

Yes, indeed.
I haven't gone through everything yet.
I want to see if there are more cases before reporting it.

Add value types and enums to various parameters

47a40cb

Suzanna-Linn commented Jun 22, 2026

View reviewed changes

Suzanna-Linn changed the title ~~Adding info to generate wiki tables~~ [RFC] Adding info to generate wiki tables Jun 22, 2026

Suzanna-Linn commented Jun 22, 2026

View reviewed changes

Rider-Linden mentioned this pull request Jun 24, 2026

Rulesets for table-based function params #143

Merged

tapple mentioned this pull request Jun 24, 2026

Associate LSL Functions with Enums #113

Open

Suzanna-Linn mentioned this pull request Jun 30, 2026

Adding info to generate wiki tables (constants) #167

Draft

Uh oh!

Conversation

Suzanna-Linn commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Suzanna-Linn Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Suzanna-Linn Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Suzanna-Linn Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tapple Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Suzanna-Linn Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tapple Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Suzanna-Linn Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Suzanna-Linn commented Jun 22, 2026 •

edited

Loading

Suzanna-Linn Jun 22, 2026 •

edited

Loading

Suzanna-Linn Jun 23, 2026 •

edited

Loading

Suzanna-Linn Jun 22, 2026 •

edited

Loading

tapple Jun 22, 2026 •

edited

Loading

Suzanna-Linn Jun 22, 2026 •

edited

Loading

tapple Jun 24, 2026 •

edited

Loading

Suzanna-Linn Jun 25, 2026 •

edited

Loading

tapple Jun 22, 2026 •

edited

Loading