Module godotnim

This module defines NimGodotObject and toVariant/fromVariant converters for Nim types. The converters are used by gdobj macro to import/export values from/to Godot (editor, GDScript).

You can also allow conversion of any custom type MyType by implementing:

proc godotTypeInfo*(T: typedesc[MyType]): GodotTypeInfo
proc toVariant*(self: MyType): Variant
proc fromVariant*(self: var MyType, val: Variant): ConversionResult

Implementing godotTypeInfo is optional and is necessary only if you want the type to be editable from the editor.

Types

NimGodotObject = ref object of RootObj
  godotObject: ptr GodotObject
  linkedObject: NimGodotObject ## Wrapper around native object that is the container of the Nim "script"
                             ## This is needed for `of` checks and `as` conversions to work as
                             ## expected. For example, Nim type may inherit from ``Spatial``, but the
                             ## script is attached to ``Particles``. In this case conversion to
                             ## ``Particles`` is valid, but Nim type system is not aware of that.
                             ## This works in both directions - for linked native object this
                             ## reference points to Nim object.
  isRef*: bool
  isFinalized: bool
  isNative: bool
The base type all Godot types inherit from. Manages lifecycle of the wrapped GodotObject.   Source Edit
ConversionResult = enum
  OK, TypeError,               ## Type mismatch
  RangeError                  ## Types match, but the value is out of range.
            ## Mainly used for numeric (ordinal) types.
Conversion result to return from fromVariant procedure.   Source Edit
CallError = object of Exception
  err*: VariantCallError       ## The error as returned by Godot
  
Raised by wrappers in case of an incorrect dynamic invocation. For example, if incorrect number of arguments were passed or they had unexpected types.   Source Edit
GodotTypeInfo = object
  variantType*: VariantType
  hint*: GodotPropertyHint
  hintStr*: string ## Format depends on the type and the hint.
                 ## For example, for Enum ``hint`` this is a comma separated list of
                 ## values.
                 ## See documentation of ``GodotPropertyHint`` for description of formats.
  
Type information provided to Godot editor   Source Edit

Vars

classRegistryStatic: TableRef[cstring, ObjectInfo]
Compile-time variable used for implementation of several procedures and macros   Source Edit
refClasses = newSeq(0)
  Source Edit

Procs

proc isFinalized(obj: NimGodotObject): bool {.
inline, raises: [], tags: []
.}
  Source Edit
proc getClassName(o: NimGodotObject): string {.
raises: [], tags: []
.}
  Source Edit
proc deinit(obj: NimGodotObject) {.
raises: [], tags: []
.}
Destroy the object. You only need to call this for objects not inherited from Reference, where manual lifecycle control is necessary.   Source Edit
proc nimGodotObjectFinalizer[T: NimGodotObject](obj: T)
  Source Edit
proc asNimGodotObject[T: NimGodotObject](godotObject: ptr GodotObject;
                                       forceNativeObject, noRef: bool = false): T
Wraps godotObject into Nim type T. This is used by godotapigen and should rarely be used by anything else.   Source Edit
proc newVariant(obj: NimGodotObject): Variant {.
inline, raises: [], tags: []
.}
  Source Edit
proc asObject[T: NimGodotObject](v: Variant): T {.
inline
.}
Converts v to object of type T. Returns nil if the conversion cannot be performed (v's type is not an Object or it's an object of an incompatible type)   Source Edit
proc asObject(v: Variant; T: typedesc[NimGodotObject]): T:type {.
inline
.}
Converts v to object of type T. Returns nil if the conversion cannot be performed (v's type is not an Object or it's an object of an incompatible type)   Source Edit
proc `as`[T: NimGodotObject](obj: NimGodotObject; t: typedesc[T]): T

Converts the obj into the specified type. Returns nil if the conversion cannot be performed (the obj is not of the type T)

This can be used either in dot notation (node.as(Button)) or infix notation (node as Button).

  Source Edit
proc `of`[T: NimGodotObject](obj: NimGodotObject; t: typedesc[T]): bool {.
inline
.}
Godot-specific inheritance check.   Source Edit
proc getSingleton[T: NimGodotObject](): T
Returns singleton of type T. Normally, this should not be used, because godotapigen wraps singleton methods so that singleton objects don't have to be provided as parameters.   Source Edit
proc gdnew[T: NimGodotObject](): T
Instantiates new object of type T.   Source Edit
proc newCallError(err: VariantCallError): ref CallError {.
raises: [], tags: []
.}
Instantiates CallError from Godot err.   Source Edit
proc newConversionError(err: ConversionResult): ref ValueError {.
raises: [], tags: []
.}
Instantiates error raised by godotapigen generated code in case of a conversion error.   Source Edit
proc setGodotObject(nimObj: NimGodotObject; obj: ptr GodotObject) {.
inline, raises: [], tags: []
.}
Used from Godot constructor produced by gdobj macro. Do not call.   Source Edit
proc setNativeObject(nimObj: NimGodotObject; nativeObj: NimGodotObject) {.
inline, raises: [], tags: []
.}
Used from Godot constructor produced by gdobj macro. Do not call.   Source Edit
proc removeGodotObject(nimObj: NimGodotObject) {.
inline, raises: [], tags: []
.}
Used from Godot destructor produced by gdobj macro. Do not call.   Source Edit
proc `==`(self, other: NimGodotObject): bool {.
inline, raises: [], tags: []
.}
Compares objects by referential equality.   Source Edit
proc godotObject(nimObj: NimGodotObject): ptr GodotObject {.
inline, raises: [], tags: []
.}
Returns raw poitner to GodotObject. Use only if you know what you are doing.   Source Edit
proc godotTypeInfo(T: typedesc[NimGodotObject]): GodotTypeInfo {.
inline
.}
  Source Edit
proc toVariant(self: NimGodotObject): Variant {.
inline, raises: [], tags: []
.}
  Source Edit
proc fromVariant[T: NimGodotObject](self: var T; val: Variant): ConversionResult
  Source Edit
proc toVariant(self: Variant): Variant {.
inline, raises: [], tags: []
.}
  Source Edit
proc fromVariant(self: var Variant; val: Variant): ConversionResult {.
inline, raises: [], tags: []
.}
  Source Edit
proc godotTypeInfo(T: typedesc[SomeGodotOrNum]): GodotTypeInfo {.
inline
.}
  Source Edit
proc godotTypeInfo(T: typedesc[range]): VariantType {.
inline
.}
  Source Edit
proc toVariant[T: SomeGodotOrNum](val: T): Variant {.
inline
.}
  Source Edit
proc fromVariant[T: SomeSignedInt or SomeUnsignedInt](self: var T; val: Variant): ConversionResult
  Source Edit
proc godotTypeInfo(T: typedesc[enum]): GodotTypeInfo
  Source Edit
proc toVariant[T: enum](self: T): Variant {.
inline
.}
  Source Edit
proc fromVariant[T: enum](self: var T; val: Variant): ConversionResult {.
inline
.}
  Source Edit
proc fromVariant[T: SomeFloat](self: var T; val: Variant): ConversionResult
  Source Edit
proc fromVariant[T: SomeGodot](self: var T; val: Variant): ConversionResult
  Source Edit
proc godotTypeInfo(T: typedesc[string]): GodotTypeInfo {.
inline
.}
  Source Edit
proc toVariant(s: string): Variant {.
inline, raises: [], tags: []
.}
  Source Edit
proc fromVariant(s: var string; val: Variant): ConversionResult {.
raises: [], tags: []
.}
  Source Edit
proc godotTypeInfo(T: typedesc[seq]): GodotTypeInfo
  Source Edit
proc godotTypeInfo(T: typedesc[array]): GodotTypeInfo
  Source Edit
proc toVariant[T](s: seq[T]): Variant
  Source Edit
proc toVariant[I, T](s: array[I, T]): Variant
  Source Edit
proc fromVariant[T](s: var seq[T]; val: Variant): ConversionResult
  Source Edit
proc fromVariant[T: array](s: var T; val: Variant): ConversionResult
  Source Edit
proc godotTypeInfo(T: typedesc[Table | TableRef]): GodotTypeInfo {.
inline
.}
  Source Edit
proc toVariant[T: Table or TableRef](t: T): Variant
  Source Edit
proc fromVariant[T: Table or TableRef](t: var T; val: Variant): ConversionResult
  Source Edit
proc getNativeLibHandle(): pointer {.
raises: [], tags: []
.}
Returns NativeScript library handle used to register type information in Godot.   Source Edit
proc registerFrameCallback(cb: proc () {.
closure
.}) {.
raises: [], tags: []
.}
  Source Edit

Templates

template registerClass(T: typedesc; godotClassName: cstring; native: bool)
Registers the specified Godot type. Used by gdobj macro and godotapigen.   Source Edit