NameEntity

Could someone please tell me what the purpose of this command is? The docs and the book say very little about how it works, and nothing about why you'd need it. It seems to append a name to the handle, which itself is already an appendage to the ram number. A handle is more useful than a number of course, but why confuse things by adding a name too? Is that useful in some way? Here's my code:

Graphics3D 640,480,32,1
SetBuffer BackBuffer()
camera=CreateCamera()
MoveEntity camera,0,0,-10

cube=CreateCube()
EntityColor cube,127,127,127
name$=EntityName(cube)

While Not KeyHit(1)
Cls

CameraProject(camera,EntityX(cube),EntityY(cube),EntityZ(cube))
If KeyHit(49) NameEntity(cube,"graybox")

UpdateWorld
RenderWorld

If EntityInView(cube,camera)=1
Text ProjectedX#(),ProjectedY#(),   "number: " +cube 
Text ProjectedX#(),ProjectedY#()+15,"handle: cube"
Text ProjectedX#(),ProjectedY#()+30,"name: " +EntityName(cube)
EndIf
Text 7,15,"Press n to name the cube."

Flip
Wend
End

If you don't need to use it then don't.

One trick is to store a handle to a type that the 3D object is somewhat related with as the entitys name. Then on pick or collision event you can recall directly the type by using the object command on the entity's name.

But really, if you don't find a command useful then don't use it :)

From a different point of view, you can retrieve information from an entity (EntityName). You can use this to store custom properties in it.

For instance, if build a scene in a 3d editor, and you want your player blow up if he comes in contact with a certain mesh, you could store data in the namefield of the entity in the editor. Export to .b3d, then read the EntityName data . You can parse this data and see if any events (so to speak) are attached to this entity. You would have to of course have code ready to interpret any data you put in the name field and act accordingly on it.

It has lots of uses. Mostly naming entities so you can find them again later using FindChild(ent) when you have a complex model with lots of heirarchy. It just gives something more human readable. People also use them for storing metadata in their entities (eg. "Box|Metal|blue|audio:blah.mp3" ).

Also great for debugging.

Also, a handle (as you call it) is a number as well. I don't really see how entityname confuses things, if so don't use it!

NameEntity entity, namestring$ - Sets the namestring of the specified entity.
EntityName( entity ) - Returns the specified entity's namestring.

The namestring is just an ordinary string value. You can use it for whatever you want.

Most modelling programs allow you to set the namestrings of the various parts of a model, so you can use the namestrings, in combination with functions such as FindChild, to search the entity hierachy of a multi-part model for a particular entity within that hierarchy.

You can also use the namestring to store data, or references to data, within an entity. You may wish to store an array index which indexes one or more arrays which contain data about a particular group of entities, for example. You can also use the namestring in combination with the (undocumented) Handle and Object commands to store the handle for a Blitz custom Type. This can be extremely useful when you need to access the custom data associated with an entity that had its entity handle returned as part of a collision, pick, or similar operation.

Heh, well I have them documented! I have scans from the book, the online docs, the original program docs, and the downloaded docs. Still, some of the replies here confused me quite a bit because I'm still pretty new to all this, but thanks for trying. In general though, would you say for a person like me whos first language is Blitz3D, that this command is useful for those times when you say, "Hey Blitz, what's this object over here?" and Blitz replies, "Oh that? That's 123556208." and you say, "Thanks. Really, that's helpful." but with NameEntity and EntityName you're more often working with names instead?

A lot of commonly used query operations, such as collision and pick operations, will return the handle to an entity. You can then use the handle as a parameter for a lot of other entity functions, but only the entity name functions actually allow you to retrieve data that you've added to the entity yourself.

The issue is that a game object consists of more than just the data stored in its entity data space. There is usually a large amount of data used by a game object, that can't effectively be stored in that entity data space, but which you still need to be able to access with only the integer entity handle available to use to grab it. The NameEntity and EntityName functions allow you to store a string value (which can also be an integer or float value due to the way Blitz does automatic data type conversions) inside the entity. You can then use the entity handle to grab that string data, and use it for whatever purpose you wish.

An example. Note that this is untested and incomplete code.

; Create a bank used to store a single integer value.
Global G_intbank = CreateBank( 4 )

; Declare the constant used to identify the monster object class. This should be a positive, non-zero value.
Const C_MONSTER = 1

; Declare the variable which determines the maximum number of monsters which can appear in the game.
Global G_max_monsters = 10

; Declare the monster object blueprint.
Type T_monster
	Field entity
	Field name$
	Field health#
	Field strength#
	Field state
End Type

; Declare the monster objects array.
Dim A_monster.T_monster( G_max_monsters )

;.....

; Create a new monster, and give it a name.
index = 1
A_monster( index ) = New T_monster
A_monster( index )\entity = CreateCube()
A_monster( index )\name$ = "Hubert"

; Store the monster's object class number, and array index number, inside its namestring.
; These two values will be stored as two 16 bit shorts stored in a 32 bit integer.
PokeShort G_intbank, 0, C_MONSTER
PokeShort G_intbank, 2, index
NameEntity A_monster( index )\entity, PeekInt( G_intbank, 0 )

;....

; Camera pick a point in the viewport with the specified camera and grab the entity handle of any object that gets picked.
entity = CameraPick( camera, vx#, vy# )

If entity ; Make sure that the 'entity' variable contains a non-zero number, indicating that something was picked.
	
	; Extract the value stored in the picked entity's namestring, as an integer number.
	value = EntityName( entity )
	
	If value ; Make sure that the 'value' variable contains a non-zero number,
; indicating that an integer value was actually stored in the picked entity's namestring.
; This assumes that zero is not used as a valid value for object data stored in the namestring.
		
		; Store the value in the int bank so it can then be extracted as two short values.
		PokeInt G_intbank, 0, value
		
		; Get the object's class number.
		object_class = PeekShort( G_intbank, 0 )
		
		; Get the object's index number.
		index = PeekShort( G_intbank, 2 )
		
		Select object_class
				
			Case C_MONSTER
	
				; Display the name of the monster.
				Text 10, 10, A_monster( index )\name$
				
		End Select
		
	EndIf
	
EndIf

Aw geez, no it didn't work. I tried putting Graphics3D and everything at the beginning, but I guess that wasn't enough. No big deal if you don't have time to fix it, but I was kind of looking forward to seeing it so I can at least semi finalize my NameEntity folder.

The code wasn't really intended to be run. It was just an example of how the entity namestring could be used to store information for use in a project.

If I get time, I'll try to knock-up a working example.

Based on Bill's code above:

Graphics3D 1024,768,32,2

Global light = CreateLight()
Global sky=CreateSphere(50)
EntityColor sky,0,156,196
ScaleEntity sky,30,10,30
FlipMesh sky
ground=CreatePlane(1)
EntityColor ground,48,56,8
TranslateEntity ground,0,-5,0
EntityOrder sky,999

Global camera=CreateCamera()
MoveEntity camera, 0,0,-5
RotateEntity camera,0,0,180
; Create a bank used to store a single integer value.
Global G_intbank = CreateBank( 4 )

; Declare the constant used to identify the monster object class. This should be a positive, non-zero value.
Const C_MONSTER = 1

; Declare the variable which determines the maximum number of monsters which can appear in the game.
Global G_max_monsters = 10

; Declare the monster object blueprint.
Type T_monster
	Field entity
	Field name$
End Type

; Declare the monster objects array.
Dim A_monster.T_monster( G_max_monsters )

;.....

; Create a new monster, and give it a name.
index = 1
A_monster( index ) = New T_monster
A_monster( index )\entity = CreateCube()
A_monster( index )\name$ = "Hubert"
EntityPickMode A_monster( index )\entity,2
; Store the monster's object class number, and array index number, inside its namestring.
; These two values will be stored as two 16 bit shorts stored in a 32 bit integer.
PokeShort G_intbank, 0, C_MONSTER
PokeShort G_intbank, 2, index
NameEntity A_monster( index )\entity, PeekInt( G_intbank, 0 )

;....

While Not KeyDown(1)
HidePointer
TurnEntity camera,MouseYSpeed(),0-MouseXSpeed(),0
RenderWorld 
; Camera pick a point in the viewport with the specified camera and grab the entity handle of any object that gets picked.
entity = CameraPick( camera, 512,360 )

If entity ; Make sure that the 'entity' variable contains a non-zero number, indicating that something was picked.
	
	; Extract the value stored in the picked entity's namestring, as an integer number.
	value = EntityName( entity )
	
	If value ; Make sure that the 'value' variable contains a non-zero number,
; indicating that an integer value was actually stored in the picked entity's namestring.
; This assumes that zero is not used as a valid value for object data stored in the namestring.
		
		; Store the value in the int bank so it can then be extracted as two short values.
		PokeInt G_intbank, 0, value
		
		; Get the object's class number.
		object_class = PeekShort( G_intbank, 0 )
		
		; Get the object's index number.
		index = PeekShort( G_intbank, 2 )
		
		Select object_class
				
			Case C_MONSTER
	
				; Display the name of the monster.

				Text 10, 10, A_monster( index )\name$
				
		End Select
		
	EndIf
	
EndIf

Flip

Wend