I need explanations ('return' keyword). [SOLVED]

[Joe]

Hello

I'd really like someone to tell me what "return X" is for.

I know if you type "return;" in your script, it stops running more commands.
But if you type e.g.: "return -1;", then, what happen?

Thankyou and sorry for making you lose your wonderful time 

[Candle]

I don't see a return X?

Code: ags

The dialog commands available are: 

add-inv X 
Adds inventory item X to the current player's inventory. This does the same thing as the AddInventory script command, but is provided here because it is frequently used in dialogs. 
give-score X 
Gives the player X points, and plays the score sound if appropriate. 
goto-dialog X 
Switches the current topic to Topic X, and displays the current list of choices for that topic. 
goto-previous 
Returns to the previous topic that this one was called from. If the dialog started on this topic, then the dialog will be stopped. 
lose-inv X 
Removes inventory item X from the current player's inventory. This does the same thing as the LoseInventory script command, but is provided here because it is frequently used in dialogs. 
new-room X 
Takes the player to room X, and aborts the conversation. Since this does not allow you to specify co-ordinates, you may need to use some Player Enters Room logic in the target screen to place the character properly. 
option-off X 
Turns option X for the current topic off, meaning it won't be displayed in the list of choices next time. 
option-off-forever X 
Turns option X off permanently. It will never again be displayed, not even if an "option-on" command is used. 
option-on X 
Turns option X for the current topic on, including it in the list of choices to the player next time they are displayed. 
play-sound X 
Plays sound effect X, similar to the Play Sound interaction command. 
return
Stops the script and returns to the list of choices. 
run-script X 
Runs global script function "dialog_request", with X passed as the single parameter. This allows you to do more advanced things in a dialog that are not supported as part of the dialog script. The "dialog_request" function should be placed in your game's global script file, as follows: 

  function dialog_request (int xvalue) {
    // your code here
  }
  
set-globalint GI VAL 
Changes script GlobalInt number GI to have the value VAL. This is equivalent to the SetGlobalInt script command, and allows you to quickly set things without having to go through a run-script just to set an int value. 
set-speech-view NAME X 
Changes character NAME's talking view to X. NAME must be their script name, and X is the number of the new talking view. Use this to easily change their facial expression during a conversation. 
stop 
Stops the conversation and returns the player to the game. 

[Joe]

Ok, maybe I didn't explain it very well.

I don't mean in Dialogs scripts, I mean in any script.

[Ashen]

Read the Forum rules - Use descriptive Thread titles.

You know how some functions provide the code with usable information, like Character.GetAtScreenXY gives a Character pointer:

Code: ags

if (Character.GetAtScreenXY(mouse.x, mouse.y) == cEgo) {
  //
}

//OR

Character *myChar = Character.GetAtScreenXY(mouse.x, mouse.y);

Well, return x; can be used to make custom functions return a value. So, for example:

Code: ags

function IsIdle(Character *Char) {
  if (Char.View == Char.IdleView) return true;
  else return false;
}

Would return 'true' if Char is idle, false otherwise, so you could do:

Code: ags

  if (IsIdle(cEgo)) {
    //Do Stuff
  }

OK, so that's a kind of pointless example, I just couldn't think of a better one that doesn't require a whole load of code to make sense. Hopefully you get the point, though. return x; makes your functions return a value, which can be an int, float, bool, String or any pointer type.

EDIT:
I should point out: function is really only the same as int, so if you want to return floats, Strings or whatever, you need to declare it as float, String, whatever, e.g.:

Code: ags

String GetName() {
  Character *theChar = Character.GetAtScreenXY(mouse.x, mouse.y);
  if (theChar != null) return theChar.Name;
  else return "";
}

Again, bad example. Check out any modules you've downloaded, chances are there'll be examples of return x; in a lot of them.

Or if someone can come up with a better explanation, that'd be great...

[Joe]

Thankyou very much.
Your explanation was right.
I just couldn't imagine "return" could mean that when i thought it was just for stop runnig more commands.

Thanks

[Khris]

Ashen explained it thoroughly, but maybe someone will find this useful. (Not a very good example, either, but what the hell.)

Calling return will exit the function immediately, so it can indeed be used to stop running more commands.

Example:

function quotient(int a, int b) {
  if (b==0) return;   // exit to avoid divide-by-zero error
  return a/b;
}

Display("10 divided by 5 is %d.", quotient(10,5));

[monkey0506]

You can only use return; for functions defined with function or void. Otherwise you will get a return-type error.

Like has been said, the return keyword makes the function stop running more commands. It just depends on the implementation as to whether a/what value is returned.

The types that can be returned by functions include:

char, short, int, String, float, bool, File*, InventoryItem*, Overlay*, DynamicSprite*, GUI*, Label*, Button*, Slider*, TextBox*, InvWindow*, ListBox*, Character*, GUIControl*, Hotspot*, Region*, DateTime*, Object*, function, or void.

function is internally defined as int, but can return any value of types bool, char, short, or int, and is special in that you also can use the return keyword without a return value (i.e., the function will return nothing, and will stop running more commands).

void means that the function will return nothing. Trying to return a value will generate an error.

Otherwise the return type must be the same as that the function was declared as or AGS will generate an error.