Add Clone to Handle methodmap

core/logic/smn_handles.cpp

@@ -119,6 +119,7 @@ REGISTER_NATIVES(handles)
 	{"CloseHandle",				sm_CloseHandle},
 	{"CloneHandle",				sm_CloneHandle},
 	{"GetMyHandle",				sm_GetMyHandle},
+	{"Handle.Clone",			sm_CloneHandle},
 	{"Handle.Close",			sm_CloseHandle},
 	{"Handle.~Handle",			sm_CloseHandle},
 	{NULL,						NULL},

plugins/include/handles.inc

@@ -78,7 +78,34 @@ native Handle CloneHandle(Handle hndl, Handle plugin=INVALID_HANDLE);
 methodmap Handle __nullable__ {
     public native ~Handle();
 
+    /**
+     * Closes a Handle.  If the handle has multiple copies open,
+     * it is not destroyed unless all copies are closed.
+     *
+     * @note Closing a Handle has a different meaning for each Handle type.  Make
+     *       sure you read the documentation on whatever provided the Handle.
+     *
+     * @error           Invalid handles will cause a run time error.
+     */
     public native void Close();
+
+    /**
+     * Clones a Handle.  When passing handles in between plugins, caching handles
+     * can result in accidental invalidation when one plugin releases the Handle, or is its owner
+     * is unloaded from memory.  To prevent this, the Handle may be "cloned" with a new owner.
+     *
+     * @note Usually, you will be cloning Handles for other plugins.  This means that if you clone
+     *       the Handle without specifying the new owner, it will assume the identity of your original
+     *       calling plugin, which is not very useful.  You should either specify that the receiving
+     *       plugin should clone the handle on its own, or you should explicitly clone the Handle
+     *       using the receiving plugin's identity Handle.
+     *
+     * @param plugin    Optional Handle to another plugin to mark as the new owner.
+     *                  If no owner is passed, the owner becomes the calling plugin.
+     * @return          Handle on success, INVALID_HANDLE if not cloneable.
+     * @error           Invalid handles will cause a run time error.
+     */
+    public native Handle Clone(Handle plugin=INVALID_HANDLE);
 };
 
 /**