chore: update listing of scene callbacks examples

Author: mwfarb

content/python/basic/parent.md

@@ -14,7 +14,7 @@ There is support to attach a child to an already-existing parent scene objects.
 ```python
 from arena import *
 
-scene = Scene(host="arenaxr.org", scene="earth")
+scene = Scene(host="arenaxr.org", scene="example")
 
 earth = GLTF(
     object_id="gltf-model_Earth",

content/python/callbacks.md

@@ -1,11 +1,11 @@
 ---
-title: Chat
+title: ChatCallbacks
 layout: default
-parent: Simple
+parent: Callbacks
 grand_parent: Python Library
 ---
 
-# Chat
+# Chat Callback
 
 Extremely basic example of setting a chat message handler to echo
 chat messages typed in the scene.

content/python/simple/chat.md renamed to content/python/callbacks/chat_callbacks.md

@@ -0,0 +1,45 @@
+---
+title: Callbacks
+nav_order: 1.6
+layout: default
+has_children: true
+parent: Python Library
+---
+
+# ARENA Library Scene Callbacks
+
+Library supported callback functions.
+
+### Adding callbacks when you instantiate the class
+
+You can also add callbacks like so:
+
+```python
+from arena import *
+
+def on_msg_callback(scene, obj, msg):
+    pass
+
+def new_obj_callback(scene, obj, msg):
+    pass
+
+def delete_obj_callback(scene, obj, msg):
+    pass
+
+scene = Scene(..., on_msg_callback=on_msg_callback, new_obj_callback=new_obj_callback, delete_obj_callback=delete_obj_callback)
+```
+
+## Custom Message Callbacks
+
+If you need to use an MQTT client, the `Scene` object exposes a way to use its MQTT client to subscribe to custom topics.
+
+```python
+def led_toggle(client, userdata, msg):
+    # do stuff here
+
+scene.message_callback_add("custom/control/light", led_toggle)
+```
+
+## Scene callbacks
+
+There are a number of scene callbacks you can use in the table of contents below.

content/python/callbacks/index.md

@@ -0,0 +1,27 @@
+---
+title: MsgCallbacks
+layout: default
+parent: Callbacks
+grand_parent: Python Library
+---
+
+# All Messages Callback
+
+`scene.on_msg_callback` is called whenever there is a new message sent to the client. Use this whenever you want to sniff out **all** incoming messages.
+
+```python
+from arena import *
+
+scene = Scene(host="arenaxr.org", scene="example")
+
+# [scene] is the Scene that called the callback
+# [obj] will be an Object instance
+# [msg] is the raw JSON message as a dict
+def on_msg_callback(_scene, obj, _msg):
+    # do stuff with obj here
+    print("msg", obj, obj.data.position)
+    # etc.
+    # could also do obj["object_id"] or msg["object_id"]
+
+scene.on_msg_callback = on_msg_callback
+```

content/python/callbacks/msg_callbacks.md

@@ -0,0 +1,45 @@
+---
+title: ObjectCallbacks
+layout: default
+parent: Callbacks
+grand_parent: Python Library
+---
+
+# Object Callbacks
+
+`scene.new_obj_callback` is called whenever there is a new object that has been created in the scene,
+one that the user does not have a reference to. Use this to make references to any
+new objects that may appear during a programs lifetime. Also a good way to find camera ID's.
+
+`scene.delete_obj_callback` is called whenever there is an object has been deleted in the scene.
+arena-py will look for all "action" = "delete" messages and call this callback.
+Use this to delete references and to be notified when an object is removed by
+another user or program.
+
+```python
+from arena import *
+
+scene = Scene(host="arenaxr.org", scene="example")
+
+# [scene] is the Scene that called the callback
+# [obj] will be an Object instance
+# [msg] is the raw JSON message as a dict
+def new_obj_callback(scene, obj, msg):
+    # do stuff with obj here
+    print("new", obj, obj.object_id, obj.data.position.x)
+    # etc.
+    # could also do obj["object_id"] or msg["object_id"]
+
+scene.new_obj_callback = new_obj_callback
+
+# [scene] is the Scene that called the callback
+# [obj] will be an Object instance
+# [msg] is the raw JSON message as a dict
+def delete_obj_callback(scene, obj, msg):
+    # do stuff with obj here
+    print("delete", obj, obj.object_id, obj.data.position.x)
+    # etc.
+    # could also do obj["object_id"] or msg["object_id"]
+
+scene.delete_obj_callback = delete_obj_callback
+```

content/python/callbacks/object_callbacks.md

@@ -0,0 +1,30 @@
+---
+title: ProgramCallbacks
+layout: default
+parent: Callbacks
+grand_parent: Python Library
+---
+
+# Program Callbacks
+
+`scene.end_program_callback` is called whenever the program is ending from the SIGINT, Crtl-C, or other kill process.
+Use this to cleanup resources you don't want in the scene when the program ends.
+This is especially useful for persisted objects use created that you want to be removed.
+
+```python
+from arena import *
+
+scene = Scene(host="arenaxr.org", scene="example")
+
+childObject = Box(object_id="child_object")
+appParentObject = Object(object_id="parent_object", parent=childObject.object_id)
+
+# [scene] is the Scene that called the callback
+def end_program_callback(scene):
+    # do stuff with scene root objects here
+    scene.delete_object(appParentObject)
+    print("App Terminated.")
+    # etc.
+
+scene.end_program_callback = end_program_callback
+```

content/python/callbacks/program_callbacks.md

@@ -1,11 +1,11 @@
 ---
-title: Addtopic
+title: TopicCallbacks
 layout: default
-parent: Simple
+parent: Callbacks
 grand_parent: Python Library
 ---
 
-# Add Topic
+# Add/Remove Topic
 
 Demonstrate subscribing to a secondary topic on the same broker and monitor
 messages from the secondary topic within the same program.
@@ -16,12 +16,10 @@ import json
 from arena import *
 
 def objects_callback(_scene, _obj, msg):
-    print("Object message: "+str(msg))
+    print("Object message: " + str(msg))
 
 def secondary_callback(_scene, _obj, msg):
-    print("-----")
     print(f"Secondary message:\nTopic: {str(msg.topic)}\nPayload: {json.loads(msg.payload)}")
-    print("-----")
 
 # subscribe to objects
 scene = Scene(host="arenaxr.org", scene="example", on_msg_callback=objects_callback)
@@ -32,16 +30,13 @@ async def test():
     # subscribe to secondary
     scene.message_callback_add(topic, secondary_callback)
     print(f"Subscribed to {topic}")
-    print()
 
     # sleep for 5 seconds
     await scene.sleep(5000)
 
     # unsubscribe to secondary
     scene.message_callback_remove(topic)
-    print()
     print(f"Unsubscribed to {topic}")
-    print()
 
 # our main event loop
 scene.run_tasks()