Sanny Builder Library

[x87]

Discussion for https://library.sannybuilder.com
Prior discussion: #107

We are looking for more people to join our editors team. Drop a message here if you want to help us and the modding community!

[x87]

@XMDS @wmysterio @MatiDragon-YT please let me know if you're interested in being able to contribute to the library documentation. I can add you to the project so you can edit the commands using the web editor.

[MatiDragon-YT]

I'd be happy to help, but Mr @x87 I don't think my English is right for this project...
I think it could help more in the translation and adaptation to Spanish than in documenting in English.
I afraid things will be misinterpreted.

[x87]

I'm not a native English speaker either. Any help is appreciated.

Giving proper names and types for command params is one of the many ways to contribute. Or writing code examples. Up to you.

[wmysterio]

I can periodically make additions or changes to the opcodes by SA, if will added to library.

[x87]

Added @wmysterio

@MatiDragon-YT let me know if you change your mind and want to join.

[MatiDragon-YT]

@x87 Yesyes... i enter

[x87]

List of classes for GTA III: https://github.com/sannybuilder/library/blob/master/gta3/classes.md
List of classes for VC: https://github.com/sannybuilder/library/blob/master/vc/classes.md

I tried to be consistent and use original names when possible. I plan to use most of VC classes in San Andreas.

[wmysterio]

I plan to use most of VC classes in San Andreas.

This shouldn't be a problem. Almost all classes from VC are used in the SA. There are some differences. For example, Garage class in the SA does not have a constructor.

[Amanuttam1192]

yess

[x87]

@MatiDragon-YT thank you for doing your very first edit 🎉

[x87]

@MatiDragon-YT yes, it is auto-generated. There is no classes.db for San Andreas yet as there are no commands in class form. Once we start filling the class and member fields for commands, classes.db will have those classes.

@wmysterio I wanted to add full description later on, and first focus on naming/typing parameters. If there is a need , I can add it sooner.

[wmysterio]

@x87 Okay. Then I will focus on what is.

[x87]

@wmysterio welcome to the party 🥳

[wmysterio]

@x87 Now I in this business :)

There is a slight hiccup. The "Save to GitHub" button hides the list navigation buttons:

I want to commit several changes, not just one per page. Is it possible or not much difference how to make a commits?

[x87]

@wmysterio thanks for pointing out the issue with the pagination. I fixed it.

[x87]

I want to commit several changes, not just one per page. Is it possible or not much difference how to make a commits?

there is no limitations on number of commits or whether they should be small or big. Just use common sense and submit changes when it's appropriate.

One thing to remember is that currently all edits are kept only in the browser memory and if the page reloads or crashes they are lost. So submitting them sooner might be a better idea.

[x87]

@wmysterio @MatiDragon-YT

I made a few improvements in the editor. It now displays suggestions based on the native command name.

Example:

Here is suggests to name the class as "Object" and the member as "SetAsStealable". You can click those suggestions to insert them into the input field.

For the most common classes "Player", "Car", "Char", and "Object" the editor suggests to name the first parameter as "self" as normally it's a reference handle to the class entity (what's known as Self or This in other programming languages).

If you pick the name "self" for the first parameter the editor would suggest to type it using the class name:

Similarly, it suggests name and type for the result of constructor opcodes. Example for 0053 with blank values:

Also the editor highlights "any" type in red.

"any" is a temporary placeholder type and should be replaced with one of the correct types.

Finally, the parameter names are now automatically converted to camelCase during editing.

[x87]

the logic for suggestions is fairly straightforward and is based on the second word in the native command name. If it's PLAYER, CHAR, OBJECT, CAR, VEHICLE, or CAM it recognized as a possible candidate for a suggestion.

If you have any ideas how to improve, or what classes to add to this list, please share.

[wmysterio]

Here is suggests to name the class as "Object" and the member as "SetAsStealable". You can click those suggestions to insert them into the input field.

Yes. I noticed this and used it.

the editor suggests to name the first parameter as "self

And I haven't seen it yet :) I will use hints, they will help in many ways.

If you have any ideas how to improve, or what classes to add to this list, please share.

Menu (Panel), Group, DecisionMaker, GroupDecisionMaker, Searchlight. ObjectPath to VC?

---

What class should the opcodes that start with "TASK_*" be classified into? Char, TaskSequence? Also, tasks can take both a specific actor and -1.

[x87]

TASK_* should probably be Task.*. There is also a class to manipulate a task sequence, TaskManager or TaskSequence. I'm open to suggestions.

[MatiDragon-YT]

I like.
They are very good options for when you do not have much time :)

[wmysterio]

TASK_* should probably be Task.*.

I think so too.

There is also a class to manipulate a task sequence, TaskManager or TaskSequence. I'm open to suggestions.

I like TaskSequence.

---

Perhaps need to add a check for duplicate parameter names:

[x87]

• Added validation for duplicate params and command names.
• Added a bit of extra formatting for all inputs (removing leading and trailing whitespaces, removing all whitespaces from command names)
• Made is_constructor and is_destructor attribute combination invalid
• Added Pickup to the list of classes available for suggestions

[x87]

Classified TaskSequence commands in SA.
there is a new class TaskSequence with Open/Close/Clear/SetToRepeat methods and all other methods went to the Char and Group classes.

[x87]

I'm not sure if I like TaskSequence name, though. Looks the native name is Sequence as there are commands like SET_GROUP_SEQUENCE or GET_SEQUENCE_PROGRESS_RECURSIVE that do not have Task in them.

@wmysterio @MatiDragon-YT what are your thoughts on renaming it to just Sequence. And make Task part of the method name or drop it:

OPEN_SEQUENCE_TASK
Now: TaskSequence.Open()
After: Sequence.TaskOpen() or Sequence.Open()

CLEAR_SEQUENCE_TASK
Now: TaskSequence.Clear()
After: Sequence.TaskClear() or Sequence.Clear()

Which one is better?

[wmysterio]

I'm not sure if I like TaskSequence name, though. Looks the native name is Sequence as there are commands like SET_GROUP_SEQUENCE or GET_SEQUENCE_PROGRESS_RECURSIVE that do not have Task in them.

Hmm, it sounds convincing. It is probably best to use Sequence.

Which one is better?

If the Sequence class does not use a Task in its name, then you can simply write Sequence.Open(). The description might need to clarify that this is a task sequence.

---

There was a need to search for commands without a class. Perhaps an extra filter is needed to find such commands.

[MatiDragon-YT]

Hmm, it sounds convincing. It is probably best to use Sequence.

I agree with that. The word Sequence better describes the use of these commands, than Task

[x87]

• added classes picker that lists dynamic classes (prefixed with class) that can be constructed using an opcode (Car, Char, Blip, etc) and static classes that manipulate hardcoded game entities (Camera, World, Audio)
• added Blip to suggestions
• the member field is now disabled if the class field is blank
• the save button is disabled if there are errors in the editor

[MatiDragon-YT]

Is it ok if I use the class Android on 0A50 until 0A84?
It's that I only tried them there.

[x87]

@MatiDragon-YT Android does not seem like a correct choice for the class name. It's more like an extension name. Commands should be classified under Game. Screen., or similar static classes.

[XMDS]

@MatiDragon-YT Android does not seem like a correct choice for the class name. It's more like an extension name. Commands should be classified under Game. Screen., or similar static classes.

Essentially, I think Android OP only needs 3 categories. "GAME""Widget""hid". In addition, the output of some text subtitles can be completely classified into related subtitles. I think it is not too strict to just classify it as "screen". And the new OP made by alex may not need to be considered for the time being, it can be used as an expansion command.

[x87]

@XMDS Would you like to be added to the editors group and get access to the online editor?

[XMDS]

@XMDS Would you like to be added to the editors group and get access to the online editor?

yes!But my time is very unstable because of work

[x87]

Added an ability to reorder parameters by dragging over the box with the param number. This should be useful when the command only got input parameters and no output parameters, but you know that there should be outputs. Example, command CREATE_GROUP

https://library.sannybuilder.com/#/sa/default/062F
It has 2 input params from the initial generation. p1 and p2.

But the second parameter is actually a result variable. And you know 062F should have one input and one output parameters. Previously it could be fixed by updating the JSON file in the repo. Now you can drag and drop the second parameter into the results section, like this:

062f.mp4

[XMDS]

About the new class of mobile SA：

{
          "id": "0A51",
          "name": "IS_WIDGET_PRESSED",
          "num_params": 1,
          "short_desc": "If a widget icon on the screen is pressed, it returns true."
          "class": "TouchInterface",
          "input": [
            {
              "name": "WidgetID",
              "type": "int"
            }
          ],
          "attrs": {
            "is_condition": true
          }
        },

for:

TouchInterface.isWidgetPressed(1)

Touches related to widget icons on the screen should be classified as "TouchInterface". It comes from the CTouchInterface function

[x87]

Probably can create another static class Widget.

IS_WIDGET_PRESSED => Widget.IsPressed
GET_WIDGET_VALUE => Widget.GetValue
...

[wmysterio]

@x87, @XMDS For the Input class, can set operations with keyboard, mouse, touch etc. Similar work with input operations is implemented in many game engines.

Input.IsButtonPressed(...) // 00E1
Input.IsSkipCutsceneButtonPressed(...) // 08D0
Input.IsPressingAttackButton(...) // 0585
Input.IsFireButtonPressed(...) //  093F nop

Input.GetPCMouseMovement(...) // 0A4A
Input.IsMouseUsingVerticalInversion(...) // 0A4C	

Input.IsWidgetPressed(...) // XXXX Mobile

Input.IsPS2KeyboardKeyPressed(...) // 0735 PS2
Input.IsPS2KeyboardKeyJustPressed(...) // 0736 PS2

Input.IsXBOXPlayer2PressingStart(...) // 0A4E XBOX

Input.IsKeyPressed(...) // 0AB0 CLEO

Whether it is worth doing an additional classification (Keyboard, Mouse, Touch, Widget), I do not know.

[XMDS]

@x87, @XMDS For the Input class, can set operations with keyboard, mouse, touch etc. Similar work with input operations is implemented in many game engines.

Input.IsButtonPressed(...) // 00E1
Input.IsSkipCutsceneButtonPressed(...) // 08D0
Input.IsPressingAttackButton(...) // 0585
Input.IsFireButtonPressed(...) //  093F nop

Input.GetPCMouseMovement(...) // 0A4A
Input.IsMouseUsingVerticalInversion(...) // 0A4C	

Input.IsWidgetPressed(...) // XXXX Mobile

Input.IsPS2KeyboardKeyPressed(...) // 0735 PS2
Input.IsPS2KeyboardKeyJustPressed(...) // 0736 PS2

Input.IsXBOXPlayer2PressingStart(...) // 0A4E XBOX

Input.IsKeyPressed(...) // 0AB0 CLEO

Whether it is worth doing an additional classification (Keyboard, Mouse, Touch, Widget), I do not know.

I do not recommend this. Because the class name is very vague, and secondly, we should distinguish OP such as buttons, mouse, and touch (to be precise, we need to distinguish between PC and Android). Android not only supports buttons, but also supports touch, double-click, slide, and left shift. , Shift right and other operations. I think the "Widget" class can be used. In addition, I think the Android part can be done by me,

[XMDS]

The widget includes button icons, hud icons, etc. This is a category unique to Android, and it is not a correct way to classify it as input. And Android MOD players are now accustomed to the name of the icon cfg file like widget is also called "widget", so this is better

[x87]

@XMDS Hi! Thanks for your first contribution.
Can you please login in the library with your GitHub creds and edit commands using our full-featured online editor? It has many built-in features and validations and should help us to minimize the amount of errors.

To login in the library, click the Login button in the header, and authorize the Sanny Builder OAuth app, it will issue an authorization token using GitHub SSO. You can commit the changes to the repo directly from the browser

[XMDS]

@XMDS Hi! Thanks for your first contribution.
Can you please login in the library with your GitHub creds and edit commands using our full-featured online editor? It has many built-in features and validations and should help us to minimize the amount of errors.

To login in the library, click the Login button in the header, and authorize the Sanny Builder OAuth app, it will issue an authorization token using GitHub SSO. You can commit the changes to the repo directly from the browser

I also want to do this. The problem is that every time I enter the library page, I click to enter one of the SA VC 3 pages. The command has not been loaded, it has been rotating and loaded. . .

[x87]

You mean the library does not display any commands? Is there any error in the browser console, or in the network tab (right click anywhere and select Inspect Element to open browser dev tools)?

[XMDS]

Yes, it does not display the command, it has been rotating and loading. Only when I use VPN can I see the commands normally, but using vpn is too troublesome.

[x87]

Hard to tell without error logs from the browser console, but I assume you can't access githubusercontent.com from where the library loads JSON files. I've updated the base url to load them via jsdelivr.com, can you check now if it works? Try to clear the browser cache before opening the library.

[XMDS]

Hard to tell without error logs from the browser console, but I assume you can't access githubusercontent.com from where the library loads JSON files. I've updated the base url to load them via jsdelivr.com, can you check now if it works? Try to clear the browser cache before opening the library.

Yes, it has been resolved now I can see the command normally

[x87]

I noticed something in recent commits by @wmysterio
sannybuilder/library@7063b2a
sannybuilder/library@2d3ad91
sannybuilder/library@e9e3a38

it looks like after switching to jsdelivr JSON files get cached more aggressively. It results in loading an outdated JSON and losing previously made changes.

I will take a look into making sure the cache is busted after loading the library. For now, extra refresh (F5) after opening the library should force the browser to load the most recent JSON file. Edit: should be done.

[wmysterio]

@x87 I noticed that many of the changes were not being applied. Between the second and third update, I deliberately reset my browser cache. I decided that the browser was to blame.

---

I also noticed that if move the input field to the command results, then the drop-down list is set to "var_any". However, it is saved as "any". Need to manually set the value before save to "var_any".

[x87]

@wmysterio

I noticed that many of the changes were not being applied. Between the second and third update, I deliberately reset my browser cache. I decided that the browser was to blame.

can you please make several small updates now and see if the latest fix helps to keep them?

[wmysterio]

@x87 Sure. Wait a second. Doesn't apply changes. There are more edits in the commit history than I have done.

[x87]

I also noticed that if move the input field to the command results, then the drop-down list is set to "var_any". However, it is saved as "any". Need to manually set the value before save to "var_any".

this is fixed. now a param gets source: var_any or source: any when moved between input and output lists

[x87]

Looks like the caching issue after switching to jsdelivr is deeper than I thought. CDN caches files up to one year and they are slow on reflecting changes as they come (24 hours after pushing a new commit to master), so just adding a timestamp won't bust the cache.

I'm looking for alternatives to githubusercontent that are able to load static files from the library repo and reflect the changes immediately. Maybe GitHub API will work...

[x87]

I have replaced jsdelivr with the github api call for commands json loading. Please let me know if notice any issues with this approach.

[XMDS]

@x87 "Class" is how to deal with reverse judgment grammar.
0256——8256
E.g:

Player.Defined(0)

not ？

[x87]

not Player.Defined(0)

[XMDS]

@x87 Should we add a "platform" tag to certain commands? (PC, XBOX, PSP, PS2, Mobile). I believe you should also notice that a certain OP does not exist on a certain platform (NOP), but it does exist on another platform.

[x87]

For now I would like to focus on PC only opcodes. I'm aware that some opcodes exist/work only on certain platforms, but adding this type of classification is not a top priority. When we get to the point most of the PC commands are classified we can also add more platforms.

[x87]

linking the relevant ticket sannybuilder/library#38

[MatiDragon-YT]

Forms of destruction

With so many methods to destroy something from the game, I think it would be more optimal to follow this way to name the destructors:

Remove

For those who are instantly destroyed.

009B DELETE_CHAR
00A6 DELETE_CAR
0164 REMOVE_BLIP
018E REMOVE_SOUND
040D CLEAR_MISSION_AUDIO
04EF REMOVE_ANIMATION
061E CLEAR_ATTRACTOR
0632 REMOVE_GROUP
065C REMOVE_DECISION_MAKER
06D6 DELETE_CHECKPOINT
08DA DELETE_MENU
0A41 REMOVE_USER_3D_MARKER
0AA3 FREE_DYNAMIC_LIBRARY
0AAE REMOVE_AUDIO_STREAM

Free

For those who destroy themselves when they stop consuming or seeing them.

01C2 MARK_CHAR_AS_NO_LONGER_NEEDED
01C3 MARK_CAR_AS_NO_LONGER_NEEDED
01C4 MARK_OBJECT_AS_NO_LONGER_NEEDED
06EB MARK_VEHICLE_MOD_AS_NO_LONGER_NEEDED

Disappear

For those who are destroyed with the Fade effect.

034F REMOVE_CHAR_ELEGANTLY
09A2 REMOVE_OBJECT_ELEGANTLY
0650 KILL_FX_SYSTEM

---

These are just a few of all the opcodes on https://library.sannybuilder.com

[x87]

Good classification here, definitely worth placing in the documentation somewhere.

However we don't pursue renaming original commands. They have their own quirks but this is what we have. Custom names can be ambiguous too. For example, I would name 01C2-01C4, 06EB as .Release(), not .Free().

Naming commands is a difficult task and luckily for us game developers already made it, so we don't have this headache anymore.

[MatiDragon-YT]

You're right .Release () would be better than .Free ().

[x87]

Opened a new discussion for the new feature (Decision Trees)
#162

[wmysterio]

I cannot compile the original "main.scm" file with this command using the class:

// 05B6: SAVE_STRING_TO_DEBUG_FILE
Debugger.SaveStringToDebugFile("CURRENT_WANTED_LIST = ") // Error 0014

[MatiDragon-YT]

SB does not support math symbols within STRINGS well. And if you use a CLASS, the spaces that the STRING contains will produce another error.

If you have to work with STRINGS, do it with the OPCODES or KEYWORDS format so that SB works a little better.

The #66 describes some of these errors.

[x87]

Yes, string compilation is a bit problematic right now. Now that I'm done with v3.8 I'm going to prioritize this issue. Unfortunately due to some implementation limits there is no a straightforward fix, so some major refactoring is needed.

[x87]

@XMDS SET_CURRENT_DIRECTORY should be a static class. It affects not only the current script (however it should, see cleolibrary/CLEO4#38), but the entire game state, therefore it can not be classified as a keyword.

[wmysterio]

I noticed that the parameters of the 03CF: LOAD_MISSION_AUDIO command for VC and SA are different, since the data types are not identical:

Audio.LoadMissionAudio(slotId: MissionAudioSlot, name: string) // VC & SA now
Audio.LoadMissionAudio(slotId: MissionAudioSlot, audioId: int) // need for SA

How do I fix this? It does not work through the SBL interface.

[x87]

you can update sa.json directly

[wmysterio]

I have updated the "sa.json" file. Now everything is displayed correctly. What I can't say about icons:

I expected this:

Is this the expected result or have I not changed the additional information somewhere? If I understood correctly, by default, the highlighting of icons goes to the number of parameters, without taking into account their data types.

[x87]

highlighting of icons goes to the number of parameters, without taking into account their data types.

this is correct. param types are not taken into account when comparing two commands.

[x87]

Renamed 3DMarker->User3DMarker as 3DMarker is an invalid identifier (can not start with a digit).

[ahmad8648]

HI,THANKS FOR EVERYONE, FOR THIS WORK

[ahmad8648]

HI, I NEED HELP IN OPCODE { 04ED: load_animation } the problem is = String 'sunbathe' is too long.
Max 7 symbols. } how i can fix it? please help me because i want make sunbathe anim mod for gta vc mobile

look to my script

{$CLEO .csi}
0000:

:GTAMODS
wait 0
if and
player.Defined($303)
not actor.Driving($304)
not actor.Dead($304)
jf @GTAMODS
04ED: load_animation 'sunbathe'
if or
84EE: not animation 'sunbathe' loaded
8256: not player $303 defined
then
004E: end_thread
end
0372: set_actor $304 anim 28 wait_state_time 60000000 ms
if
00E1: player 0 pressed_button 19
then
053D: clear_actor $304 wait_state
04EF: release_animation 'sunbathe'
end
004E: end_thread

[ahmad8648]

I JUST WANT COMPILE IT BUT THE PROBLEM !!! :(

[x87]

Strings in Vice City are limited to 7 characters. this is the game limitation.

[x87]

March 2022 Updates

• Extension badges now serve as links
  
  Clicking CLEO opens a list of commands that belong to this extension
  https://library.sannybuilder.com/#/sa/CLEO

• Added ImGui extension in SA (classic) - for this plugin https://github.com/user-grinch/ImGuiRedux

• Started adding CLEO+ commands - for this plugin https://github.com/JuniorDjjr/CLEOPlus

• For the getter or setter command (starts with GET_ or SET_) "See also" now shows its pair
  

[x87]

April 2022 Updates

• library now has two new hosts: Unknown (x86) and Unknown (x64). They list commands made with CLEO Redux SDK

• files in the download section split into two groups: for Sanny builder and for CLEO Redux
  

• when downloading JSON file with commands it's now possible to configure which extensions to add to the file (example for San Andreas - sa.json)
  

• hamburger menu appears in the sticky header when you scroll down the command list
  

• command info correctly displays other games even if the command is in a different extension, e.g. https://library.sannybuilder.com/#/unknown_x86/dylib/LOAD_DYNAMIC_LIBRARY now has links to https://library.sannybuilder.com/#/gta3/CLEO/LOAD_DYNAMIC_LIBRARY
  

• library support commands without id (used in Unknown (x86-x64))
  

• support for command names in urls, e.g. https://library.sannybuilder.com/#/sa_unreal/default/NOP

• correctly search opcodes with id larger than 0FFF, e.g. BEEF is a negative form of opcode 3EEF

• added extra validation for opcode field and auto-correction
  

[x87]

May 2022 Updates

• Sanny Builder Library welcomes a new title: GTA IV is the first game in the RAGE era to be documented alongside older GTA 3D series.
  IV Natives documentation is available here: https://library.sannybuilder.com/#/gta_iv
• The website was updated from Angular 11 to the latest Angular 13.

[x87]

June 2022 Updates

• each game now has a list of extensions. A link to the list is placed next to Classes and Enums links.
  

• Filter by extensions is updated to include "Any extension" option

• An issue with wrong links in command descriptions that mention commands from another extensions has been fixed (example: 0D39). Additionally command names (in UPPER_CASE) are now links too (example: GET_PLAYER_ID).

• File size of support-info.json has been reduced to save network traffic. Additionally enum names have been packed into a single file (enums-info.json) reducing number of extra calls the library makes on initial load.

[x87]

September 2022 Updates

• Sanny Builder Library welcomes Liberty City Stories https://library.sannybuilder.com/#/lcs. At the moment missing lots of original names and is work-in-progress.
• Commands can now have full descriptions in Markdown format https://library.sannybuilder.com/#/sa/default/0001
  The descriptions can be customized per game:
  • https://library.sannybuilder.com/#/gta3/default/IS_PLAYER_IN_TAXI
  • https://library.sannybuilder.com/#/vc/default/IS_PLAYER_IN_TAXI
  • https://library.sannybuilder.com/#/lcs/default/IS_PLAYER_IN_TAXI

[xChillax]

Hello, I've been modding Bully for years since the very early days of modding (back at the bully-board forums), while I didn't publicly publish my work most of the time I've been creating scripts with Lua in the past and having my own little documentation of what every single Lua function does, and I decided to take a look at the documentation for the game when I was coding with Cleo Redux and... and it's pretty barebones and missing a lot; I can barely work on complex ped related stuff that rely on specific functions that are currently not present by default (I mean, they are there but it would be nice to have them under the classes and some kinda don't even work).

I was wondering a few things:

1. Could I get access to the website editor? I noticed some typos here and there, there's also a lot of functions that were not included within a proper class, etc. Also, is there also any guidelines to follow when filling in the data?
2. I noticed some classes use camelCase instead of PascalCase for some reason. It's a bit concerning considering how in site the Char class methods, such as GetTargetPed, are in PascalCase but... in game to actually use them I had to use camelCase, so it was getTargetPed instead. At least that's what I experienced from the lastest release version of Cleo Redux.
3. I was also wondering if there it could be a possibility of also adding new helper functions that don't exist within the game to make modding easier? (while I could make my own personal library and share it around for people to use it, it would be nicer if everyone had access to extra functions by default)

Oh, and I got a huge list of enums that I used before for my lua mods for plenty of functions, so I would love to have them over here as well since it is much cleaner than having to remember every single number and their possible meaning.

Thanks in advance! :)