Guide to the Godot game engine/Servers (singletons)

Servers in Godot are for low-level engine manipulation, like changing the volume of sounds, creating collision objects and more. A "Server", in this sense, is a "singleton" (meaning it is loaded/created only once, and cannot be duplicated or instanced). For the sake of simplicity, on this page, any use of the word "singleton" refers to these servers.

Nodes are just "things" that make use of singleton and present the user high-level (easier) manipulation, which can only go so far.


These are the limitations of a node-based system:

  1. It's slower in runtime
  2. Godot's source code becomes slightly more complex
  3. It's harder to control them in different threads
  4. More memory is required.


Strengths of the node system are:

  1. It's simpler
  2. It's less likely to cause bugs in your game
  3. It's less confusing and more attractive - it draws users is with its simplicity
  4. It's faster to set up Node trees than call each singleton's functions for everything


Whether you use high-level, low-level or a combination of both is completely up to you and the game you are making.

Some games simply need the functionality of a singleton since nodes just don't offer the functionality you need, or making that functionality with nodes would be too difficult, time consuming, computationally expensive, or all three of those things.

Many server functions return or use RIDs (Resource ID). They must be kept stored in a variable to remain modifiable. In the case of Resource types, like textures, you must store the resource as a variable as well, or both it and its corresponding RID will be erased.

For more information on usage, see the docs.

VisualServer

edit

NOTE: Godot's API for everything visual will change in Godot 4

The VisualServer creates a 2D "canvas" and a 3D "scenario", which can be given objects, both 2D and 3D, to draw. They will not draw unless you use a Viewport node.

Use VisualServer.canvas_item_set_parent(<Item RID>, get_canvas()) to add an item to the main canvas. You can create a canvas to use its RID with var canvas=VisualServer.canvas_create(). You can attach a canvas to a Viewport with VisualServer.canvas_item_set_parent(<canvas RID>, <Viewport RID>), providing it is not already attached to one.

For 3D, use VisualServer.scenario_create() for a new scenario, Spatial.get_world().scenario for the existing scenario and VisualServer.instance_set_scenario(<Item RID>, <Scenario RID>) for adding an object/light to a scenario.

CanvasItems and VisualInstance nodes contain methods that allow drawing directly. In 2D, you can draw circles and rectangles, as well as textures and text. Using VisualInstance, you can draw meshes into 3D.

Helpful simple methods:

# Set the textures of the black borders when using stretch_mode ProjectSettings
VisualServer.black_bars_set_images(left, top, right, bottom)

# Force the screen to update immediately
VisualServer.force_draw()
# Attach a new Viewport and disable the root
func _ready():
  get_viewport().set_attach_to_screen_rect(Rect2()) # Sets the rect to zero size
  # To get <Viewport RID>, call get_rid() on the chosen Viewport Node
  VisualServer.set_attach_to_screen_rect(<Viewport RID>, Rect2(0, 0, 600, 600)) # You can also use other sizes and offsets
# The reason you must disable the root Viewport is because it is drawn last,
# or in other words,  drawn over the others. As it has no transparent pixels
# in the default settings, it would override every pixel on the screen.

# Detach a Viewport from the screen
VisualServer.viewport_detach(<Viewport RID>)

Example of drawing a texture with 25 width and height:

extends Node2D

var texture = preload("res://assets/weapons/sword.png")
func _ready():
  var sprite = VisualServer.canvas_item_create()
  VisualServer.canvas_item_add_texture_rect(Rect2(0, 0, 25, 25), texture.get_rid())
  VisualServer.canvas_item_set_parent(sprite, get_canvas())

AudioServer

edit

The AudioServer is used for low-level audio access. It can also record and playback recorded audio. This is useful when implementing voice-chat in games.

The AudioServer does not use RIDs.


 

To do:
I do not know how to use this server. Please help!


PhysicsServer

edit

The server for 3D physics.

Physics servers are for creating areas and bodies, but do not place them on the scene tree.

The below code creates a wall that is 5 units high, half a unit thick, and 4 units wide and adds it the the physics space.

extends Spacial

func _ready():
  var wall = PhysicsServer.body_create(0)
  var shape = PhysicsServer.shape_create(PhysicsServer.SHAPE_BOX)
  PhysicsServer.shape_set_data(shape, Vector3(0.5, 5, 4))
  PhysicsServer.body_add_shape(body, shape)
  PhysicsServer.body_set_space(body, get_world().space) 

Physics2DServer

edit

The 2D version of PhysicsServer. It is used in exactly the same way, but some values may need to be adjusted, like Vector3s to Vector2s.

ARVRServer

edit

The ARVRServer, or the XRServer, is the heart of Godot's advanced XR solution, and handles all the processing.


See also: XR Godot tutorials.

CameraServer

edit

The CameraServer is not used to keep track of Camera nodes like it sounds. It is a server to use external cameras. Like the camera at the back of your phone. It can take pictures, but is mostly used in AR.

This server doesn't use RIDs.


 

To do:
I don't know how to use this server. Please help!



Guide to the Godot game engine

Getting started [edit]
Installation
What is a node?
Programming
Resources and importing
Signals and methods
Your first game
Making it work
Debugging
Input
Physics
Saving and loading
Multiplayer
Making it look good
UI skinning
Animation
Advanced help
Servers (singletons)
Platform specific
Optimisation
Encryption
Exporting
Plugins
Miscellaneous
Helpful links
Authors and contributors
Print version


<-- previous back to top next -->