NodeMapper 1.0

Godot plugin to map nodes to variables

How to use

The following image shows a sample scene tree. In the scene script, declare variables for the nodes that you wish to access, even if those nodes are in a sub-scene. However all node names must be unique except for those in discrete scenes. NodeMapper will report an error when more than one node tries to map to the same variable. Discrete scene node names must be prefixed with the $ character. In the root scene where the variables reside, call map_nodes() function in NodeMapper to assign the nodes to those variables. This operation must be done in the _ready() function before accessing node variables.

# res://scenes/Main.gd
extends Panel

var lblVersion
var txtName
var btnClear
var btnSave
var DiscreteScene

func _ready():
    NodeMapper.map_nodes(self)

Once map_nodes() function returns, you can access the nodes through the variables. If you get a null error, check to make sure the variable and node name is exactly the same. For discrete nodes, the variable name will be the node name but without the $ character prefix. NodeMapper does not map the children of discrete nodes but can still map the discrete node itself. This allows sub-scenes to perform their own mapping. The parent scene can still access the children nodes through variables in the sub-scenes once they are mapped. Node names will not need to be unique across discrete scenes.

func _ready():
    NodeMapper.map_nodes(self)
    DiscreteScene.txtContent.connect("text_changed", self, "on_txtContent_changed")
    btnClear.connect("pressed", self, "on_btnClear_pressed")
    lblVersion.text = NodeMapper.VERSION
    txtName.grab_focus()

func on_btnClear_pressed() -> void:
    txtName.text = ""
    txtName.grab_focus()

func on_txtContent_changed() -> void:
    btnSave.disabled = DiscreteScene.txtContent.text == ""

Each scene that has its own mapping can be instanced in a parent scene as discrete. By prefixing the node name with $ character, NodeMapper will not attempt to map the nodes in the scene to variables in the root scene. The root scene can still access the nodes through the variables in the discrete scene.

# res://scenes/DiscreteScene.gd
extends PanelContainer

var txtContent
var btnClear

func _ready() -> void:
    NodeMapper.map_nodes(self)
    btnClear.connect("pressed", self, "on_btnClear_pressed")

func on_btnClear_pressed() -> void:
    txtContent.text = ""
    txtContent.emit_signal("text_changed")
    txtContent.grab_focus()

Exporting variables

Scanning through the scene tree to map nodes to variables can be time consuming especially when you have a large and complex scene tree. While NodeMapper is essential during development, we can remove its use in production by first exporting the mapped variables. Call export_vars() function instead of map_nodes() to export the mapping to an external script.

func _ready():
    NodeMapper.export_vars("res://scenes/Main_vars.gd", self)
    DiscreteScene.txtContent.connect("text_changed", self, "on_txtContent_changed")
    btnClear.connect("pressed", self, "on_btnClear_pressed")
    lblVersion.text = NodeMapper.VERSION
    txtName.grab_focus()

The following shows the content of the exported file.

# res://scenes/Main_vars.gd
extends Panel

onready var lblVersion: Label = get_node("Examples/SameScene/lblVersion")
onready var txtName: LineEdit = get_node("Examples/SubScene/Form/txtName")
onready var btnClear: Button = get_node("Examples/SubScene/Form/btnClear")
onready var btnSave: Button = get_node("Examples/SubScene/Form/btnSave")
onready var DiscreteScene: PanelContainer = get_node("Examples/$DiscreteScene")

You can now remove the variables from the scene script and inherit instead them from the exported file. Once your scene tree is stabilized, you can remark off the export_vars() statement. Make sure to re-export if you make changes to your scene tree that includes the name and position of existing nodes or adding new nodes that require variable mapping. If you change the base type of your root scene node, you must also update the base node type in the export file.

# res://scenes/Main.gd
extends "res://scenes/Main_vars.gd"

func _ready():
#	NodeMapper.export_vars("res://scenes/Main_vars.gd", self)
    DiscreteScene.txtContent.connect("text_changed", self, "on_txtContent_changed")
    btnClear.connect("pressed", self, "on_btnClear_pressed")
    lblVersion.text = NodeMapper.VERSION
    txtName.grab_focus()

func on_btnClear_pressed() -> void:
    txtName.text = ""
    txtName.grab_focus()

func on_txtContent_changed() -> void:
    btnSave.disabled = DiscreteScene.txtContent.text == ""

# res://scenes/DiscreteScene.gd
extends "res://scenes/DescreteScene_vars.gd"

func _ready() -> void:
#	NodeMapper.export_vars("res://scenes/DescreteScene_vars.gd", self)
    btnClear.connect("pressed", self, "on_btnClear_pressed")

func on_btnClear_pressed() -> void:
    txtContent.text = ""
    txtContent.emit_signal("text_changed")
    txtContent.grab_focus()