====== Programming ======

In sBotics, robot programming is the main activity to be performed by the user. This page explores the functionalities of the programming menu, the types of programs you can create, and important concepts for robot programming.

===== Accessing the Programming Screen =====

The robot menu can be accessed through the second button at the bottom of the simulator interface (HUD).

{{ :HUD.png?400|Programming Menu }}

On this screen, you can:

  - Create, modify, and delete programs;
  - Switch the language between **BlockEduc**, **rEduc**, and **C#**;
  - Save the program and send it to the robot (compile);
  - Import / Export program files.

{{:programacao.png|Programming Menu}}

> **Tip!** If your written program (not BlockEduc) becomes too large (+700 lines), we recommend using VSCode to program in the simulator. Simply look for the "Switch Modes" button with the VSCode symbol to switch. VSCode is more efficient for very large codes and prevents the simulator from becoming too slow with your code.
===== Difficulty Hierarchy =====
sBotics languages follow a hierarchy of difficulties. **All programming can be converted to higher difficulty levels.**

{{ switch_language.png?200}}
That is, given the hierarchy below:
  - [[en:BlockEduc]] (Easiest)
  - [[en:rEduc]] (Intermediate)
  - [[en:csharp|C#]] (Most difficult)
It is always possible, by programming in an easier language, to convert your code to a more difficult language using the language switch function at the top of the programming screen.

That is, BlockEduc is a converter/facilitator for rEduc, which is a converter/facilitator for C#. All code made in BlockEduc is converted to rEduc, which is then converted to C# to be executed by the simulator (which internally only processes C#).

> **We do not intend to make converters for easier languages because the purpose of sBotics is to introduce people to robotics education, and we want users to progress in difficulty and skill.**

In general, we always advise using **[[en:rEduc]]** for your programs. However, if you are not familiar with text-based programming or already know advanced programming, there is no problem in using [[en:BlockEduc]] and [[en:csharp|C#]]. Just understand that each language will bring advantages and disadvantages, such as less control over routines in the case of BlockEduc and a steep learning curve in the case of C#.
===== Understanding Synchronous Programming (Advanced) =====
Imagine that sBotics is like a stage where the robot performs its actions. In a traditional robot, it is its own stage, where it does its things without worrying too much about what might happen to the program. If the program is inefficient and causes memory to run out, the robot will simply shut down or stop. It is important to understand that sBotics and your robot share the same stage. An inefficient function in your robot can make the entire sBotics slow, or even exhaust the program's memory as a whole.

> **For those more studied in programming:** sBotics runs on the same "thread" as the user's program due to Unity. Previously, we used multi-threaded programming, but it was extremely inefficient and caused many memory leaks.

How does this affect programming? (in [[en:csharp|C#]])
  * "While true": Indiscriminate "while true" statements crash sBotics, as it waits for the robot to finish something that never finishes before continuing to run the simulator.
  * Waiting is important: In real robotics, commands take time to execute. Now, in sBotics, you **must** use a command called "wait" to simulate this waiting time. This allows sBotics to continue functioning while the robot performs its actions.

**In rEduc/BlockEduc, the use of "wait" is optional**, as all repetition structures in rEduc/BlockEduc, when converted, already have a built-in wait.

> **For the studied:** Busy-waiting is not an option; sBotics does not allow you to block the thread with infinite and inefficient checks. You need to wait at some point in your repetition structures to allow space for the simulator to "breathe." The fewer spaces given for the simulator to breathe, the slower the simulator's performance will be.

This way of processing everything on the same "stage" (thread) means that some problems can occur if the user is not careful with their own code.
===== Common Errors / Crashes =====
There are some errors that **may seem to be from the simulator**, but are entirely **caused by user programming** affecting the simulation platform itself.

==== Memory Exhaustion ====
When the simulator closes randomly without any explanation, it is **most likely** because the simulator consumed more memory than allowed and the application was forcefully terminated. Check for indiscriminate use of variables and consider reusing variables that are no longer in use. Additionally, the simulator becomes heavy as the user uses it, so it is always recommended to restart the program at least once per hour.

==== Busy Waiting ====
{{ not_responding.png?300}}
If the program "stops responding" and displays the infamous "sBotics is not responding" message, it is most likely because a loop structure was used improperly (in C# without any wait) or the simulator was unable to complete the commands of the loop structure within the simulator's standard loop time (because your program is too heavy). In this case, consider adding a ''%wait%'' of 100ms in your loop structures to give the program more time to "breathe."

{{ crash_handler.png?300}}
==== Crash Handler ====
If you see a window like the one on the side with this symbol or the sBotics symbol, it's because the simulator was about to crash / close (for one of the reasons already mentioned) and the "crash handler" was activated. However, it most likely indicates only memory exhaustion or a very heavy program.

==== How to Resolve? ====
To solve problems with your code, always separate your code into tasks, functions, and blocks that you can comment out or remove to test cases in isolation. This way, you can get a better idea of what is happening and where. In the vast majority of cases, problems that result in crashes come from inefficient programming, which has too many unnecessary loops and calculations. Check your repetition structures (while, for, repeat, etc.) and make sure the functions being performed are efficient, and if a functionality is too heavy, always consider putting one or more "''%%wait%%''" inside that repetition.