Adding KubeJSable to Addons

[TechTastic]

Proposed Changes

I am adding a page to the Wiki under Addons for KubeJSable, my new addon.
This page contains a text blob and two tabs. The first tab is Events and under it will be listed the three exposed Sable events Pre, Post, and Ready, as headings, with a text blob explaining the event and a code block showcasing how to intercept them.
The second tab is Bindings which will have 4 inner tabs for Shared/Common, Server, Client, and Startup specific bindings. Each inner tab shows the available bindings and all exposed methods with a list.

[KonSola5]

1. There's a bit of Kubedoc grammar leaking through. This also happens on other tabs.

2. Please format the lines in bindings, server, client and startup tab as code - currently they are as plain text. Try using $$ syntax or `[ts]code` syntax, as your definitions are structured like TypeScript types. Also, if some types are type wrappable or KubeJSable adds new type wrappers, please document that you can use some other kind of object in place of some type. This only applies to the values the scripter provides, and not to types that you are getting from a provided callback's parameters.

[TechTastic]

1. I see, I dont honestly konw how to resolve this as this is the format given by this project's README for tabs.
   There is also a second issue which is that Server, Client, and Startup are meant to be sub-tabs/inner tabs of Bindings

|>
<||>
<|

2. I see, I will add the [ts]code blocks as needed. About extra wrappers, I add none besides these bindings, what existing wrappers exist so that I may replace the parameters with them?

[KonSola5]

One trick you can employ is to write your contents of tabs in a variable callout block.
Quite often, there are bugs when kubedoc syntax is inside of tables, tabs, etc.

You create them like this:

>>> #item-description
Creates `ItemStack`s from strings and other objects.
<<<

and use them later like this:

<#item-description>

(replace item-description with your identifier)

[TechTastic]

One trick you can employ is to write your contents of tabs in a variable callout block. Quite often, there are bugs when kubedoc syntax is inside of tables, tabs, etc.

You create them like this:

>>> #item-description
Creates `ItemStack`s from strings and other objects.
<<<

and use them later like this:

<#item-description>

(replace item-description with your identifier)

Ok, I got what your were putting down

[KonSola5]

You messed up: The reference to a callout block is not {{#bindings-tab-contents}}, it's <#bindings-tab-contents>.

[KonSola5]

Also, FYI: You can preview your changes:
https://kubejs.com/wiki/preview/104

[TechTastic]

You messed up: The reference to a callout block is not {{#bindings-tab-contents}}, it's <#bindings-tab-contents>.

Fixed, also mistyped |>+

[TechTastic]

Also, FYI: You can preview your changes: https://kubejs.com/wiki/preview/104

Nice!

[KonSola5]

Everything renders properly, and code blocks are properly formatted.

[KonSola5]

After discussing this a bit with Don, I'll request some changes regarding the contents:
1.

This event is fired from `ForgeSablePrePhysicsTickEvent` just before the next physics tick.
The event object itself includes a `SubLevelPhysicsSystem` (`physicsSystem`) instance and a `timeStep` value

https://github.com/TechTastic/wiki/blob/82c9621b37d3f34bfff44634b973f4dbf8d64548/wiki/addons/kubejsable/page.kubedoc#L99-L100

Are those implementation details really necessary? Also, what physicsSystem contains? What kind of number is timeStep (integer? float/double?) and what it measures (ticks? seconds?)

`[ts]distanceSquaredWithSubLevels(level: Level, a: Vector3dc, b: Vector3dc): double`

(all the type definitions)

Please try to explain, what each parameter is, and maybe explain what can be passed in place of the parameter, if applicable.
Also, on what object are the methods defined?
For example:

**Syntax**
```js
something.distanceSquaredWithSubLevels(level, a, b)
```
**Parameters**
- `[js]level` - A `Level` (explain what kind of level this should be)
- `[js]a` - A `Vector3dc` representing a first point in 3D space. It may be a JS array of exactly 3 number elements representing the x, y, and z coordinate respectively, for example `[js]\[10, 25, -5.5]`.
- `[js]b` - A `Vector3dc` representing a second point in 3D space. It may be a JS array of exactly 3 number elements representing the x, y, and z coordinate respectively, for example `[js]\[10, 25, -5.5]`.
**Return value**
Square of a distance between point `a` and point `b`.
**Example**
(maybe even an example of usage, if this is notable enough)

where something is the object the methods are on - explain what is that object and where it comes from.

[TechTastic]

After discussing this a bit with Don, I'll request some changes regarding the contents: 1.

This event is fired from `ForgeSablePrePhysicsTickEvent` just before the next physics tick.
The event object itself includes a `SubLevelPhysicsSystem` (`physicsSystem`) instance and a `timeStep` value

https://github.com/TechTastic/wiki/blob/82c9621b37d3f34bfff44634b973f4dbf8d64548/wiki/addons/kubejsable/page.kubedoc#L99-L100

Are those implementation details really necessary? Also, what physicsSystem contains? What kind of number is timeStep (integer? float/double?) and what it measures (ticks? seconds?)

`[ts]distanceSquaredWithSubLevels(level: Level, a: Vector3dc, b: Vector3dc): double`

(all the type definitions)

Please try to explain, what each parameter is, and maybe explain what can be passed in place of the parameter, if applicable. Also, on what object are the methods defined? For example:

**Syntax**
```js
something.distanceSquaredWithSubLevels(level, a, b)

Parameters

• [js]level - A Level (explain what kind of level this should be)
• [js]a - A Vector3dc representing a first point in 3D space. It may be a JS array of exactly 3 number elements representing the x, y, and z coordinate respectively, for example [js]\[10, 25, -5.5].
• [js]b - A Vector3dc representing a second point in 3D space. It may be a JS array of exactly 3 number elements representing the x, y, and z coordinate respectively, for example [js]\[10, 25, -5.5].
  Return value
  Square of a distance between point a and point b.
  Example
  (maybe even an example of usage, if this is notable enough)

where `something` is the object the methods are on - explain what is that object and where it comes from.

1. Not really. physicsSystem is an instance of SubLevelPhysicsSystem, timeStep is a double, and I actually dont know what timeStep is necessarily meassuring, I just passed along the parameters

2. I thought it was self-explanatory that the name of the Bindings headers were the objects to use to call upon the methods. As for the parameters, I can try but it would make the already long document even longer. Also, as far as alternative parameters, what are the alternatives I need to look for? Youve provided an array of three numbers as one for Vector3d but does that also apply to Vec3, Vec3i, Vector3fc, etc?

[KonSola5]

Youve provided an array of three numbers as one for Vector3d but does that also apply to Vec3, Vec3i, Vector3fc

This is a general type wrapper for Vec3 and its derivatives - if in doubt, please check by testing in-game.

[KonSola5]

I thought it was self-explanatory that the name of the Bindings headers were the objects to use to call upon the methods

So you mean that this should be read as the method has to be called in a JS script like this:

Sable.getContaining(event.level, 1250, 1250)

I only realized that after your comment.

Also, keep in mind: A majority (99%) of KubeJS scripters won't use ProbeJS to be able to track types throughout the code. Most users write KJS scripts without any knowledge of underlaying types, so it's very important to at least try to explain, what each thing is. Don't assume that the end user is an experienced Java programmer.

[TechTastic]

Youve provided an array of three numbers as one for Vector3d but does that also apply to Vec3, Vec3i, Vector3fc

This is a general type wrapper for Vec3 and its derivatives - if in doubt, please check by testing in-game.

main.js#5: Error in 'LevelEvents.loaded': dev.latvian.mods.rhino.EvaluatorException: Can't find method io.github.techtastic.kubejsable.bindings.SableJS.distanceSquaredWithSubLevels(net.minecraft.server.level.ServerLevel,object,object)

well, it definitely did not like it when I passed in two arrays

[KonSola5]

Hmm, if this is the case then you should consider adding some type wrappers to your KubeJSable addon to make using these more scripter-friendly.

[TechTastic]

I thought it was self-explanatory that the name of the Bindings headers were the objects to use to call upon the methods

So you mean that this should be read as the method has to be called in a JS script like this:

Sable.getContaining(event.level, 1250, 1250)

I only realized that after your comment.

Also, keep in mind: A majority (99%) of KubeJS scripters won't use ProbeJS to be able to track types throughout the code. Most users write KJS scripts without any knowledge of underlaying types, so it's very important to at least try to explain, what each thing is. Don't assume that the end user is an experienced Java programmer.

Yes, and I understand, I just dislike writing extensive documentation

[TechTastic]

Hmm, if this is the case then you should consider adding some type wrappers to your KubeJSable addon to make using these more scripter-friendly.

Ok, how do I do this? I know where in the plugin to do it, but have no concept of the actual implementation of a type wrapper

[KonSola5]

Alternatively, @HideFromJS JS-unfriendly methods and inject your own JS-friendly methods that use types with well defined type wrappers.

[TechTastic]

Ok, I have re-written the mod to use existing type wrapped objects and adding bindings for Vector3d, Vector3dc, BoundingBox3ic, and BoundingBox3i classes