C# language features

This page provides an overview of the commonly used features of both C# and Godotand how they are used together.

Type conversion and casting

C# is a statically typed language. Therefore, you can't do the following:

varmySprite=GetNode("MySprite");mySprite.SetFrame(0);

The methodGetNode() returns aNode instance.You must explicitly convert it to the desired derived type,Sprite2D in this case.

For this, you have various options in C#.

Casting and Type Checking

ThrowsInvalidCastException if the returned node cannot be cast to Sprite2D.You would use it instead of theas operator if you are pretty sure it won't fail.

Sprite2DmySprite=(Sprite2D)GetNode("MySprite");mySprite.SetFrame(0);

Using the AS operator

Theas operator returnsnull if the node cannot be cast to Sprite2D,and for that reason, it cannot be used with value types.

Sprite2DmySprite=GetNode("MySprite")asSprite2D;// Only call SetFrame() if mySprite is not nullmySprite?.SetFrame(0);

Using the generic methods

Generic methods are also provided to make this type conversion transparent.

GetNode<T>() casts the node before returning it. It will throw anInvalidCastException if the node cannot be cast to the desired type.

Sprite2DmySprite=GetNode<Sprite2D>("MySprite");mySprite.SetFrame(0);

GetNodeOrNull<T>() uses theas operator and will returnnull if the node cannot be cast to the desired type.

Sprite2DmySprite=GetNodeOrNull<Sprite2D>("MySprite");// Only call SetFrame() if mySprite is not nullmySprite?.SetFrame(0);

Type checking using the IS operator

To check if the node can be cast to Sprite2D, you can use theis operator.Theis operator returns false if the node cannot be cast to Sprite2D,otherwise it returns true. Note that when theis operator is used againstnullthe result is always going to befalse.

if(GetNode("MySprite")isSprite2D){// Yup, it's a Sprite2D!}if(nullisSprite2D){// This block can never happen.}

You can also declare a new variable to conditionally store the result of the castif theis operator returnstrue.

if(GetNode("MySprite")isSprite2DmySprite){// The mySprite variable only exists inside this block, and it's never null.mySprite.SetFrame(0);}

For more advanced type checking, you can look intoPattern Matching.

Preprocessor defines

Godot has a set of defines that allow you to change your C# codedepending on the environment you are compiling to.

Examples

For example, you can change code based on the platform:

publicoverridevoid_Ready(){#if (GODOT_MOBILE || GODOT_WEB)// Use simple objects when running on less powerful systems.SpawnSimpleObjects();#elseSpawnComplexObjects();#endif}

Or you can detect which engine your code is in, useful for making cross-engine libraries:

publicvoidMyPlatformPrinter(){#if GODOTGD.Print("This is Godot.");#elif UNITY_5_3_OR_NEWERprint("This is Unity.");#elsethrownewNotSupportedException("Only Godot and Unity are supported.");#endif}

Or you can write scripts that target multiple Godot versions and takeadvantage of features that are only available on some of those versions:

publicvoidUseCoolFeature(){#if GODOT4_3_OR_GREATER || GODOT4_2_2_OR_GREATER// Use CoolFeature, that was added to Godot in 4.3 and cherry-picked into 4.2.2, here.#else// Use a workaround for the absence of CoolFeature here.#endif}

Full list of defines

  • GODOT is always defined for Godot projects.

  • TOOLS is defined when building with the Debug configuration (editor and editor player).

  • GODOT_REAL_T_IS_DOUBLE is defined when theGodotFloat64 property is set totrue.

  • One ofGODOT_LINUXBSD,GODOT_WINDOWS,GODOT_OSX,GODOT_ANDROID,GODOT_IOS,GODOT_WEBdepending on the OS. These names may change in the future.These are created from theget_name() method of theOS singleton, but not every possible OSthe method returns is an OS that Godot with .NET runs on.

  • GODOTX,GODOTX_Y,GODOTX_Y_Z,GODOTx_OR_GREATER,GODOTX_y_OR_GREATER, andGODOTX_Y_z_OR_GREATER, whereX,Y,andZ are replaced by the current major, minor and patch version of Godot.x,y, andz are replaced by all values from 0 to the current version number for thatcomponent.

    Note

    These defines were first added in Godot 4.0.4 and 4.1. Version defines forprior versions do not exist, regardless of the current Godot version.

    For example: Godot 4.0.5 definesGODOT4,GODOT4_OR_GREATER,GODOT4_0,GODOT4_0_OR_GREATER,GODOT4_0_5,GODOT4_0_4_OR_GREATER, andGODOT4_0_5_OR_GREATER. Godot 4.3.2 definesGODOT4,GODOT4_OR_GREATER,GODOT4_3,GODOT4_0_OR_GREATER,GODOT4_1_OR_GREATER,GODOT4_2_OR_GREATER,GODOT4_3_OR_GREATER,GODOT4_3_2,GODOT4_3_0_OR_GREATER,GODOT4_3_1_OR_GREATER, andGODOT4_3_2_OR_GREATER.

Whenexporting, the following may also be defined depending on the export features:

  • One ofGODOT_PC,GODOT_MOBILE, orGODOT_WEB depending on the platform type.

  • One ofGODOT_WINDOWS,GODOT_LINUXBSD,GODOT_MACOS,GODOT_ANDROID,GODOT_IOS, orGODOT_WEB depending on the platform.

To see an example project, see the OS testing demo:https://github.com/godotengine/godot-demo-projects/tree/master/misc/os_test

User-contributed notes

Please read theUser-contributed notes policy before submitting a comment.