Ok, here’s how it breaks down.
There are a number of types of lights: ambient, point, directional, spotlight. Each of these is represented by a node that lives somewhere in the scene graph. The position and orientation of the light is determined by the basic scene graph operations like setPos(), setHpr(), etc.
Because of a problem with multiple inheritance, for the moment you have to call upcastToPandaNode() to put a light in the scene graph, like this:
spot = Spotlight('spot')
spotNP = render.attachNewNode(spot.upcastToPandaNode())
Now that you have a NodePath that references your spotlight, you can put it wherever in the scene graph you want it to be; for instance, parent this to your car to make a headlight, or leave it under render and just position it somewhere:
spotNP.setPos(10, 0, 2)
spotNP.lookAt(myAvatar)
But so far the light doesn’t actually illuminate anything, it’s just there, invisible. In order to turn the light on, you have to first decide what object or objects will be illuminated by the light. To do this, use the nodePath.setLight() method. If you want your light to illuminate the whole world (or rather, whatever it might be pointing at), that really means everything under render, so you call:
render.setLight(spotNP)
To turn the light off again, you can remove the light setting from render:
render.clearLight(spotNP)
Ambient lights work the same way as spotlights, except it doesn’t matter where they are or which way they’re facing (since ambient lights are by definition uniform everywhere in space). To create an ambient light and apply it just to one object:
amb = Ambient('amb')
ambNP = render.attachNewNode(amb.upcastToPandaNode())
myObject.setLight(ambNP)
And to turn it off again:
myObject.clearLight(ambNP)
Note that the default color for an ambient light is (1, 1, 1, 1), which is also the default illumination you get if there are no lights on an object at all. So the above will have no apparent effect. If you want to be able to see the ambient light, you either need to darken the rest of the world (for instance, by applying a darker ambient light to render), or color the light red or something, like this:
amb.setColor(VBase4(1, 0, 0, 1))
Ironically, using lights can only make things darker than not having lights at all (since if you have no lights, it is as if you had everything fully illuminated, but as soon as you have at least one light, that light determines the brightness level).
If your only purpose is highlighting an object, consider using something like object.setColorScale(1, 0, 0, 1) (and object.clearColorScale()) instead. This is a simpler way to quickly change the color of an object. Again, it can only make things darker, since the default is for things to be as bright as they can be.
David