Graal Bible - User contributions [en]

Graal3D Scripting Manual

2021-12-01T16:33:01Z

Julienm20: Added a section to link to the form to get access to testbed3d server to start development.

== Intro ==
[[File:Graal kart start.jpg|center|frame]]
Welcome to the Graal3D Scripting Manual!

This Manual comes in handy for beginners wanting to learn Graal3D Scripting, and advanced developers looking to expand their knowledge, as it contains documentation, examples, tutorials and much more...

What we will focus on in this Manual is programming our gameplay (scripting the behavior of our GameObjects, their interactions, the components attached to them...)

==== How things work in Unity: ====
Unity is the leading platform for building 2D, 3D, VR and augmented reality games. It offers a scripting API in C#, allowing us to interact with the unity editor and the games we want to build.

In the Unity editor, we create and add GameObjects to our scene, we then attach C# scripts to each that will all run upon starting the scene. Unity sort of runs everything for you, it reads through all the lights, cameras, meshes, behaviors… and processes it for you.

==== How things work in Graal3D: ====
Since we will be using the Graal Unity Binding, things will be a bit different.

The Graal Unity Binding is a binding between GraalScript and Unity, it is actually still in alpha, but most functionalities needed are present. The goal of this binding is to mimic the Unity C# scripting system (functions and classes). So if you are familiar with Unity and C#, everything should be easy. If not, then do not worry, I will go over everything step by step and include examples done in C# and compare them to GraalScript for each topic.

The Worlds Client (which you will have to download) will serve as the Unity base scene where you instantiate your GameObjects and manipulate them with your GraalScripts.

==== Required Downloads: ====
'''Unity 2020.2.2f1:''' <nowiki>https://unity3d.com/get-unity/download/archive</nowiki>

'''The Worlds Client:''' <nowiki>https://www.graalonline.com/playerworlds/downloads/file?name=WorldsSetup64-518.exe</nowiki>

'''RC:''' More here ([[Creation/Management/Remote Control|RC]]) or download directly here http://fp4.ca/windows_rc3_beta.zip

==== Get Started With Testbed3D Development: ====
After downloading Unity, the worlds client, and RC3, you can now submit through the google form below to be given access to testbed3D and start your GS2 and Graal3D scripting journey.

[http://fp4.ca/windows_rc3_beta.zip https://forms.gle/4oYnmKzQ85MVDyB99]
[[File:RC3 testbed3D.png|center|frameless|388x388px]]

Once you login in RC3 and see "Testbed3d" in your server list congratulations you have been accepted and can now start development on the Testbed3D server.

==== Tools ====
In-game Unity Tools (''mimic the Unity Editor)'' & Game Functionality Tools ''(warping, fixing graphics, starting minigames...):'' <u>[[Tools]]</u>

== Documentation ==

==== Unity ====

* [[Overview On Unity Basics]]

==== AssetBundles ====

* [[Uploading and Loading AssetBundles]]
*[[Placing GameObjects in NPC]]

==== Examples and Tutorials ====
*[[Getting Started Examples]]
*[[3DTutorials|Tutorials]]
*[[Unity UI]]

==== Classes, Functions and Variables ====

* [https://quattro3d.graalonline.com/Documentation/ Quattro3D Scripting]

File:RC3 testbed3D.png

2021-12-01T15:50:24Z

Julienm20:

The server that you will see when logging in to RC3 when allowed to enter testbed development

Unity UI

2021-11-16T15:42:01Z

Julienm20:

[[File:UnityUI.png|thumb|889x889px|none]]In this section we will go over an example of making a UI on unity and uploading and coding it on Client3D in graalscript.

'''Unity Part:'''

Open the “Quattro3D- Unity Project for bundle asset creation” folder using unity hub.

To the assets folder, add we add a folder that will hold all the prefabs of the assetbundle.

To the scene, add a Canvas (in the Hierarchy, right click -> UI -> Canvas). The Canvas will hold all the elements of our UI (buttons, text, scrollbar, images…).

Select the Canvas and in the Inspector go to '''Canvas Scaler''' and select '''Scale With Screen''' for '''UI Scale Mode'''. This will allow the canvas Canvas to expand to full screen on all screens.

Now to build the UI you see above (devtools). Start by adding Text elements (right click on Canvas -> UI -> Text).

For each element, change the name and the text according to its function, change the color to white, add a button component and add a animation component. In the '''Rect Transform''' component, in the Anchor Presets, hold Alt and select top left to position your element.

Add all the Text elements and position them (Inspector, Bundle Explorer, Console, Camera, Rendering).

Now, to add the back button. Add an Image element to the UI, change its name to “back”, and in the image component add the source of the image (drop down in our case). Rotate it -90 deg on the Z axis for it to face left. Add a button component to turn it to a back button that closes the devtools.

For the grey background you see, add and image just like before, change its color to black and change the A field in RGBA to 48 to make it transparent. Add an '''Outline''' component and change the '''Effect Color''' to white to add an outline to the image.
[[File:Unity UI.png|none|thumb|1006x1006px]]

Now that we’ve added all our elements to the Canvas, it’s time to create our animations.

To create an animation, in the top menu (next to Files, Edit, Assets…) go to Window -> Animation -> Animation.

The animation tab should open in the bottom. Select the component you want to create an animation for and create and name the animation.

We will be doing the sliding background image example for the animation.

To record the animation, press on the record button. We want the image to slide in. So put the cursor on time 0s, and change the Pos X to -65 (outside of the screen) then move the cursor to 4s and change the Pos X back to 65. Press the record button again to save the recording.
[[File:Unity UI anim.png|none|thumb|1032x1032px]]

You can press play to view your animation in action. To add the animation to the element; simply add an animation component and add the source of the animation you just created.

Same thing goes for all the other animations.

'''Graal Script Part:'''

Now that we’ve created our prefabs and added the animations, our canvas is ready to be uploaded on the server and scripted. Save the AssetBundle and upload it to the server ([[Uploading and Loading AssetBundles]] for more info).
findplayer("Graal5918039").addweapon(this.name);

//#CLIENTSIDE

function onPlayerChats() {
if (player.chat == "dev") toggle();
}

public function toggle() {
(@"3D/Dev/AssetManager").loadAssetBundle("devtoolsui");
}

function onAssetBundleDownloaded(bundlename) {
if (bundlename == "devtoolsui") {
this.keepAlive = true;;
this.btns = {"inscpector", "bundleexpl", "console", "camera", "rendering", "back"};
this.devuiprefab = GameObject::fromassetbundle("devtoolsui", "assets/menuui/canvasdevtools.prefab");
this.devui = Object::Instantiate(Type::GameObject, this.devuiprefab);

for (btn : this.btns) {
temp.btn = Quattro::TransformExtensions::FindDeepChild(this.devui.transform, btn);
Quattro::EventManager::AddEventHandlerTo(temp.btn.gameobject.GetComponent(Type::UI::Button));
this.catcheventobject(temp.btn.gameobject, "onClick", "onDevToolClick");
}

Object::Destroy(this.devui, 4);
}
}

public function onDevToolClick(go) {
if (go.name == "inscpector") player.chat = go.name;
if (go.name == "bundleexpl") player.chat = go.name;
if (go.name == "console") player.chat = go.name;
if (go.name == "camera") player.chat = go.name;
if (go.name == "rendering") player.chat = go.name;

if (go.name == "back") close();
}

public function close() {
for (btn : this.btns) {
temp.btn = Quattro::TransformExtensions::FindDeepChild(this.devui.transform, btn);
Object::Destroy(temp.btn.gameobject);
}

temp.img = Quattro::TransformExtensions::FindDeepChild(this.devui.transform, "Image");
temp.anim = temp.img.gameobject.GetComponent(Type::Animation);
temp.anim.play("devtools2");
}
We load the assetbundle the usual way:
(@"3D/Dev/AssetManager").loadAssetBundle("devtoolsui");
function onAssetBundleDownloaded(bundlename) {
if (bundlename == "devtoolsui") {
'''''this.keepAlive = true;''''' is necessary for the weapon to keep checking for button clicks.

We create and instantiate the canvas prefab.
this.devuiprefab = GameObject::fromassetbundle("devtoolsui", "assets/menuui/canvasdevtools.prefab");
this.devui = Object::Instantiate(Type::GameObject, this.devuiprefab);
this will display the canvas on the client screen.

To detect button clicks;
temp.btn = Quattro::TransformExtensions::FindDeepChild(this.devui.transform, btn);
Quattro::EventManager::AddEventHandlerTo(temp.btn.gameobject.GetComponent(Type::UI::Button));
this.catcheventobject(temp.btn.gameobject, "onClick", "onDevToolClick");
we first find the button GameObject by name ('''this.devui.transform''' being the transform component of the canvas, and '''btn''' is the button name we want to find).

Next, we add an EventManager to the button component of the GameObject we just found ('''temp.btn.gameobject.GetComponent(Type::UI::Button)''').

And '''this.catcheventobject(temp.btn.gameobject, "onClick", "onDevToolClick")''' to catch all the onClick events.

Finally, we implement '''public function onDevToolClick(go)''' to add functionalities after button is pressed (with '''go''' the GameObject being pressed).

For animations, to add or play an animation, you will need to get the animation component of the GameObject first. (using: '''temp.img.gameobject.GetComponent(Type::Animation)''')
temp.img = Quattro::TransformExtensions::FindDeepChild(this.devui.transform, "Image");
temp.anim = temp.img.gameobject.GetComponent(Type::Animation);
temp.anim.play("devtools2");
(more script functionalities for animations available here: https://docs.unity3d.com/ScriptReference/Animation.html).

Uploading and Loading AssetBundles

2021-10-20T10:12:23Z

Julienm20: /* Uploading AssetBundles */

Up until now, we have been using PrimitiveTypes for our GameObjects.

In this section, we will start using different GameObjects. I will go over how to upload your assetbundles containing all your customized prefabs to the server. How to load, instantiate, and manipulate them.
===Uploading AssetBundles===
You will need to have Unity installed for this part.

You will also need to have the “Quattro3D- Unity Project for bundle asset creation.7z" Unity project installed from :

https://www.graalonline.com/downloads/file?name=Quattro3D-UnityProjectforbundleassetcreation.zip

I will be going through an example, demonstrating how it’s done.

Begin by choosing what prefabs you want to upload. In our case, I will upload a bomb and a character prefab, which I already have ready in a different project.

Note: Remember you cant put scripts in your asset bundles.

Open the Unity project downloaded (“Quattro3D- Unity Project for bundle asset creation.7z"). This project contains a script that builds the assetbundles and puts them in the Assets/StreamingAssets folder, which will hold all our uploadable files.

In the Assets folder, I will create a new folder and name it Example.

Next I will import my prefabs;

In the top left menu hit (Assets>Import New Asset/Import Package). Go to the location of your prefabs and select them and press Import.

[[File:Uploading assetbundles.png|frameless|371x371px]]

[[File:Prefabs.png|frameless|476x476px]]

[[File:Imported prefabs.png|frameless|773x773px]]

Now that we’ve imported our assets, we’ll create an assetbundle to be uploaded to the server;

Using the Unity way of creating assetbundles by flagging the prefabs:

Select all the prefabs in the asset folder, the Inspector Window should open. At the bottom right of your screen, in the Inspector Window, create or select an existing name for your assetbundle.

The bundle will embed all the assets/prefabs under that flagged directory. You can of course put multiple prefabs/files/subdir...etc inside an asset bundle.

[[File:Adding a tag to the prefabs.png|frameless|541x541px]] [[File:Tagging prefabs.png|frameless|541x541px]]

Now build your asset by pressing on BuildAssetBundles>PackagesBuilder>buildAssetBundles in that project.

The built asset will be stored in the downloaded Unity Project in “Quattro3D- Unity Project for bundle asset creation\Assets\StreamingAssets”

[[File:Uploading assets to the server.png|frameless|712x712px]]

The file that we’ll use to upload to graal should end with “.txt”

[[File:Uploading to the server.png|frameless|800x800px]]

Finally to upload the asset to the server, login on rc, go to levels/assetbundles and drop the “.txt” file there.

It should be automatically downloaded to /Users/”yourusername”/AppData/LocalLow/Graal Worlds/Levels3d/assetbundles[[File:Uploading assets through rc.png|center|frameless|477x477px]]''You’re strongly advised to generate a unitypackage too when you generate an asset bundle and upload it to the server, so that everyone can rebuild the bundle on every platform.''

To view your asset and your prefabs, login to the Client, hit F10 to open the Bundle Explorer and search for your asset name.[[File:Bundle explorer.png|center|frameless|768x768px]]
===ClientSide Loading Assets===
Now to load your prefabs using GraalScript; to your code add the following:

You can use the Bundle Explorer (F10) to copy the path of the AssetBundle.
{| class="wikitable"
|findplayer("Graal5918039").addweapon(this.name);
//#CLIENTSIDE

function onCreated() {

(@"3D/Dev/AssetManager").loadAssetBundle("documentationexample");

}

function onAssetBundleDownloaded(bundlename) {

if (bundlename == "documentationexample") {

player.chat = "example loaded";

temp.prefab = GameObject::fromassetbundle("documentationexample", "assets/example/bomb.prefab");

this.bomb = Object::Instantiate(Type::GameObject, temp.prefab);

this.bomb.transform.position = v3(player.x + 5, player.z, player.y);

}

}
|}[[File:Loading prefabs.png|center|frameless|406x406px]]
{| class="wikitable"
!(@"3D/Dev/AssetManager").loadAssetBundle("documentationexample");
|}
The above method loads and downloads the AssetBundle.
{| class="wikitable"
! function onAssetBundleDownloaded(bundlename) {}
|}
And Implementing the '''''onAssetBundleDownloaded''''' will make sure the Assetbundle has been loaded. We could've skipped this step and directly created the prefab, but best is to make sure the Asset has been loaded.

We then create a prefab:
{| class="wikitable"
!temp.prefab = GameObject::fromassetbundle("documentationexample", "assets/example/bomb.prefab");
|}
instantiate it,
{| class="wikitable"
!this.bomb = Object::Instantiate(Type::GameObject, temp.prefab);
|}
and give it a position in the scene:
{| class="wikitable"
!this.bomb.transform.position = v3(player.x + 5, player.z, player.y);
|}