Level Editor/Scripting/Sandbox limits: Difference between revisions

From TeamSpec Wiki
Jump to navigation Jump to search
Level Editor: sandbox limits page
 
American spelling
 
Line 10: Line 10:
* '''Its own names''': the variables, constants and functions it declares, and their parameters.
* '''Its own names''': the variables, constants and functions it declares, and their parameters.
* '''The GDScript language''': <code>var</code>, <code>const</code>, <code>func</code>, <code>if</code>, <code>elif</code>, <code>else</code>, <code>for</code>, <code>while</code>, <code>match</code>, <code>return</code>, <code>break</code>, <code>continue</code>, <code>super</code>, and lambdas passed to <code>sort_custom</code>, <code>map</code>, <code>filter</code>, <code>reduce</code>, <code>any</code> or <code>all</code>.
* '''The GDScript language''': <code>var</code>, <code>const</code>, <code>func</code>, <code>if</code>, <code>elif</code>, <code>else</code>, <code>for</code>, <code>while</code>, <code>match</code>, <code>return</code>, <code>break</code>, <code>continue</code>, <code>super</code>, and lambdas passed to <code>sort_custom</code>, <code>map</code>, <code>filter</code>, <code>reduce</code>, <code>any</code> or <code>all</code>.
* '''Values and maths''': whole and decimal numbers, strings, vectors, colours, Arrays, Dictionaries and packed arrays, with a set of their methods, plus maths, random numbers, <code>str</code>, <code>len</code>, <code>range</code>, <code>print</code>, <code>push_warning</code> and <code>push_error</code>.
* '''Values and maths''': whole and decimal numbers, strings, vectors, colors, Arrays, Dictionaries and packed arrays, with a set of their methods, plus maths, random numbers, <code>str</code>, <code>len</code>, <code>range</code>, <code>print</code>, <code>push_warning</code> and <code>push_error</code>.


The complete list, the same one the game checks against, is on [[Level Editor/Scripting/Reference/Sandbox|What a script may use]].
The complete list, the same one the game checks against, is on [[Level Editor/Scripting/Reference/Sandbox|What a script may use]].

Latest revision as of 04:44, 20 October 2026

Map scripts run on other people's servers and machines, so they get a small, fixed set of tools. When a map loads, the game checks every script against that set, and a map with a script that uses anything else does not load at all. The check reports every offending name with its line, for example:

line 12: `OS` is not available to a server script

What a script can use

  • Its own api, and only the calls its side has. A client script cannot use a server call such as api.set_team, even if it writes the name correctly. See GamemodeServerApi and GamemodeClientApi.
  • Its own names: the variables, constants and functions it declares, and their parameters.
  • The GDScript language: var, const, func, if, elif, else, for, while, match, return, break, continue, super, and lambdas passed to sort_custom, map, filter, reduce, any or all.
  • Values and maths: whole and decimal numbers, strings, vectors, colors, Arrays, Dictionaries and packed arrays, with a set of their methods, plus maths, random numbers, str, len, range, print, push_warning and push_error.

The complete list, the same one the game checks against, is on What a script may use.

What a script cannot do

  • Load anything. load and preload are refused. A script names a pickup kind or a widget instead of loading a scene.
  • Declare a global class. class_name is refused.
  • Extend anything but its own base class. The first line is extends GamemodeServerScript, extends GamemodeClientScript or extends GamemodeBotScript; extending a path such as extends "res://..." is refused.
  • Reach the engine or the computer. OS, FileAccess, DirAccess, ClassDB, Engine, Time, nodes, the scene tree and networking are not there. Players, zones and pickups are always plain numbers and names, never objects.
  • Call things by name. call, callv, Callable, get, set and get_script are refused. That includes a Dictionary's get: write dict[key] after checking dict.has(key), or dict.get_or_add(key, default) when adding the default is what you want. A lambda can be handed to sort_custom and the like, but not called directly.
  • Change the game's randomness. seed and randomize are refused. randf, randi, randf_range and randi_range work.
  • Turn a number into an object. instance_from_id and weakref are refused.

A safe pattern for per-player data

var _streak: Dictionary = {}


func _player_died(entity_id: int, killer_id: int, default_seconds: float) -> void:
	api.respawn_in(entity_id, default_seconds)
	_streak.erase(entity_id)
	if killer_id >= 0:
		var streak: int = (_streak[killer_id] if _streak.has(killer_id) else 0) + 1
		_streak[killer_id] = streak
		if streak == 5:
			api.notify_all("%s is on a streak" % api.team_name(api.team_of(killer_id)))


func _player_left(entity_id: int) -> void:
	_streak.erase(entity_id)

Players are entity ids; there is no call that gives you a player's name, so talk about teams instead.

TeamSpec Level Editor
Basics Getting started · Interface · Viewport and camera · Selecting and hiding · Keyboard shortcuts · Settings · Map Config · Troubleshooting
Menus File · Edit · View · Tools · Functional
Panels Scene tree · Inspector · Materials · Props · Snapping · UV editor · Displacement · Terrain
Tools Move, Rotate and Scale · Box · Sphere · Cylinder · Prism · Stairs · Spiral Stairs · Spiral Tower · Arch · Path Brush · Plane · Terrain · Clip · Duplicate · Ruler and Cordon · Edit Vertex and Edge · Edit Face · Loop Cut · Material Brush · Vertex Color Brush · Displacement · Prop Path
Entities Brush · Zone · Group · Mirror Node · Prop · Spawn Point · Supply Pickup · World Boundary · Lights · Water · Sounds · Anchor Platform · Payload Track · Boss Spawn · Map Marker · World Text · Decal · Door · Button · Logic entities · 3D Skybox · Nav Region
Workflows Your first map · Brushes and CSG · Materials and UVs · Lighting and lightmaps · Bots and navigation · Mirrored maps · Outputs and logic · Custom assets · Playtesting · Exporting and publishing · Importing Source maps
Scripting Overview · Server rules · Client HUD · Bots · Teams and spawning · Zones · Pickups · Payload tracks · Map entities · Sandbox limits · Testing · King of the Hill · Team Deathmatch · API reference · What a script may use