Proposal: function property `requires-permission`

[WolfGangS]

This critical bit of information is currently hidden in the tooltips of only some functions

I propose adding a requires-permission flag

Example

functions:
  llGetCameraAspect:
    arguments: []
    energy: 10.0
    func-id: 545
    return: float
    sleep: 0.0
    tooltip: 'Returns the current camera aspect ratio (width / height) of the agent
      who has granted the scripted object PERMISSION_TRACK_CAMERA permissions. If
      no permissions have been granted: it returns zero.'
    must-use: true
    requires-permission: track-camera

Will help greatly with documentation generation

---

This repo is using Opire - what does it mean? 👇

💵 Everyone can add rewards for this issue commenting /reward 100 (replace 100 with the amount).
🕵️‍♂️ If someone starts working on this issue to earn the rewards, they can comment /try to let everyone know!
🙌 And when they open the PR, they can comment /claim #29 either in the PR description or in a PR's comment.

🪙 Also, everyone can tip any user commenting /tip 20 @WolfGangS (replace 20 with the amount, and @WolfGangS with the user to tip).

📖 If you want to learn more, check out our documentation.

[HaroldCindy]

Yep, that seems reasonable to me!

[Martin-Pitt]

Would probably make sense to rename the field to permissions to match with others like experience (otherwise rename others to e.g. requires-experience).

Had a chat with @WolfGangS and I did a quick search for functions that might use one or/and more permissions just in case and found llGetAnimationOverride which does indeed require PERMISSION_OVERRIDE_ANIMATIONS OR PERMISSION_TRIGGER_ANIMATION.

So perhaps for future proofing a string-based approach would make sense here with syntax like OR / AND keywords and (...) to cover everything possible.

For example:

functions:
  llGetAnimationOverride:
    arguments:
    - AnimationState:
        tooltip: ''
        type: string
    energy: 10.0
    func-id: 500
    return: string
    sleep: 0.0
    tooltip: Returns a string that is the name of the animation that is used for the
      specified animation state\nTo use this function the script must obtain either
      the PERMISSION_OVERRIDE_ANIMATIONS or PERMISSION_TRIGGER_ANIMATION permission
      (automatically granted to attached objects).
    must-use: true
    permissions: override-animations OR trigger-animation

[WolfGangS]

@Rider-Linden @HaroldCindy any objections to nexii's proposed format, with the OR functionality?

Though i think i might leave the names to match the PERMISSION_* constants more directly.

[Martin-Pitt]

Yeah permission constants would be fine as well

    permissions: PERMISSION_OVERRIDE_ANIMATIONS OR PERMISSION_TRIGGER_ANIMATION

Alternatively without prefix

    permissions: OVERRIDE_ANIMATIONS OR TRIGGER_ANIMATION

Whatever works

[buildersbrewery]

I assume you knew there is a category page on the slwiki as a reference:

https://wiki.secondlife.com/wiki/Category:LSL_Requires_Permissions

[Rider-Linden]

No objections from me. Using the actual permission constants will make some of the linking easier.

[HaroldCindy]

@WolfGangS I prefer just using an array with implicit OR semantics. Nothing requires AND semantics right now, just keep it simple IMO.