Merge branch 'master' of https://github.com/20tab/UnrealEnginePython

Author: rdeioris

README.md

@@ -9,15 +9,17 @@ The Python VM tries to give easy access to all of the UE4 internal api + its ref
 
 It is not meant as a way to avoid blueprints or c++ but as a good companion to them (albeit reducing the amount of c++ required for coding a game could be an interesting thing ;). If your development pipeline is already python-based (Maya, Blender, ...), this plugin could easily help you in integrating unreal into it.
 
-Another funny feature (well, a side effect ;) is that you can change your python code even after the project has been packaged. You can potentially build a completely new game from an already packaged one.
+If you want to have an idea of what the plugin can do, jump here: https://github.com/20tab/UnrealEnginePython/blob/master/tutorials/YourFirstAutomatedPipeline.md
 
 In addition to this, the plugin automatically adds an actor class (PyActor), a pawn class (PyPawn), a character class (PyCharacter) and a component class (PythonComponent) for "gentle" integration of python in your games.
 
-In the development menu, you get access to the 'PythonConsole' too, you can use it to trigger python commands directly from the editor. There is even an experimental Editor/IDE included, you can run it from the Window/Layout/Python Editor menu item.
+Another funny feature (well, a side effect ;) is that you can change your python code even after the project has been packaged. You can potentially build a completely new game from an already packaged one.
+
+Once the plugin is installed and enabled, you get access to the 'PythonConsole' item in the 'Development Menu', you can use it to trigger python commands directly from the editor. There is even an experimental Editor/IDE included, you can run it from the Window/Layout/Python Editor menu item.
 
 All of the exposed engine features are under the 'unreal_engine' virtual module (it is completely coded in c into the plugin, so do not expect to run 'import unreal_engine' from a standard python shell)
 
-The currently supported Unreal Engine versions are 4.12, 4.13, 4.14 and 4.15
+The currently supported Unreal Engine versions are 4.12, 4.13, 4.14, 4.15 and 4.16
 
 # Binary installation on Windows (64 bit)
 
@@ -47,6 +49,8 @@ git clone https://github.com/20tab/UnrealEnginePython
 
 By default the build procedure will try to discover your python installation looking at hardcoded known paths. If you want to specify a custom python installation (or the autodetection simply fails) you can change it in the Source/UnrealEnginePython/UnrealEnginePython.Build.cs file at this line: https://github.com/20tab/UnrealEnginePython/blob/master/Source/UnrealEnginePython/UnrealEnginePython.Build.cs#L10
 
+Note: ensure you have a 64bit python installation
+
 
 choose a project you want to install the plugin into, open the file explorer (you can do it from the epic launcher too) and:
 

tutorials/YourFirstAutomatedPipeline.md

@@ -1,8 +1,8 @@
-Your First Automated Pipeline with UnrealEnginePython (WORK IN PROGRESS)
+Your First Automated Pipeline with UnrealEnginePython (Part 1)
 =
 
 In this tutorial i will try to show you how to build a python script that can generate
-a new Unreal Engine 4 Blueprint implementing a Kaiju (a big Japanese monster) with its materials, animations and a simple AI based on Behavior Trees.
+a new Unreal Engine 4 Blueprint implementing a Kaiju (a big Japanese monster) with its materials and animations. In the second part a simple AI based on Behavior Trees will be added to the Blueprint as well as a bunch of simple unit tests..
 
 Running the script from the Unreal Engine Python Console will result in a native Blueprint (as well as meshes, animations, a blackboard and a behaviour tree graph) that does not require the python plugin to work.
 
@@ -77,7 +77,7 @@ ue.py_exec('name_of_script.py')
 
 ![First script in console](https://github.com/20tab/UnrealEnginePython/blob/master/tutorials/YourFirstAutomatedPipeline_Assets/first_script_console.png)
 
-Finally, download the https://github.com/20tab/UnrealEnginePython/blob/master/tutorials/YourFirstAutomatedPipeline_Assets/Kaiju_Assets.zip file and unzip it in your Desktop folder. These are the original files (fbx, tga, ...) we will import in the project using a python script.
+Finally, download the https://github.com/20tab/UnrealEnginePython/blob/master/tutorials/YourFirstAutomatedPipeline_Assets/Kaiju_Assets.zip file and unzip it in your Desktop folder. These are the original files (fbx, tga, ...) we will import in the project using a python script. The files have been 'donated' to me by Matteo Baccaro and Giacomo Caneschi of AIV (Italian Videogame Academy, http://aiv01.it)
 
 Importing the Mesh FBX
 -
@@ -133,7 +133,7 @@ The Kaiju original model is 30 meters high, so we scale it down to use it in a c
 Creating the Materials
 -
 
-The models looks good from a geometry point of view, but you can note (on the top left of the previous screenshot) that no material is assigned to the mesh.
+The model looks good from a geometry point of view, but you can note (on the top left of the previous screenshot) that no material is assigned to the mesh.
 
 We are going to create two different materials, one for the blades (Element 0) and the other for the kaiju body (Element 1)
 
@@ -196,7 +196,7 @@ slicer_texture_orm = texture_factory.factory_import_object(slicer_texture_orm_tg
 
 The textures are ready, we can start "programming" our materials adding nodes to the graphs.
 
-Let's start with the blades. The only two things to take into account is that the OcclusionRoughnessMetallic textures must have the sRGB flag turned off, and each of its channel will be mapped to a different channel:
+Let's start with the blades. The only two things to take into account is that the OcclusionRoughnessMetallic textures must have the sRGB flag turned off, and each of its color channel will be mapped to a different material component:
 
 * Green -> Roughness
 * Blue -> Metallic
@@ -415,7 +415,10 @@ blend_space_factory.TargetSkeleton = slicer_mesh.Skeleton
 # create the asset
 slicer_locomotion = blend_space_factory.factory_create_new('/Game/Kaiju/Slicer/Animations/slicer_locomotion')
 
+ue.open_editor_for_asset(slicer_locomotion)
+
 # set blend parameters
+slicer_locomotion.modify()
 slicer_locomotion.BlendParameters = BlendParameter(DisplayName='Speed', Min=0, Max=300, GridNum=2)
 
 # assign animations
@@ -425,11 +428,12 @@ slicer_locomotion.BlendParameters = BlendParameter(DisplayName='Speed', Min=0, M
 # mark them as 'valid' explicitely !
 slicer_locomotion.SampleData = [BlendSample(Animation=animation_idle, SampleValue=FVector(0, 0, 0), bIsValid=True, RateScale=1), BlendSample(Animation=animation_walk, SampleValue=FVector(150, 0, 0), bIsValid=True, RateScale=1), BlendSample(Animation=animation_run, SampleValue=FVector(300, 0, 0), bIsValid=True, RateScale=1)]
 
-# save
-slicer_locomotion.save_package()
-
 # compute blend space and update the editor preview
 slicer_locomotion.post_edit_change()
+
+slicer_locomotion.save_package()
+
+ue.close_editor_for_asset(slicer_locomotion)
 ```
 
 ![The Kaiju Locomotion BlendSpace](https://github.com/20tab/UnrealEnginePython/blob/master/tutorials/YourFirstAutomatedPipeline_Assets/slicer_locomotion.png)
@@ -456,17 +460,16 @@ anim_bp_factory = AnimBlueprintFactory()
 anim_bp_factory.TargetSkeleton = slicer_mesh.Skeleton
 
 # ensure no blueprint with the same name exists
-# get_asset() returns an exception, maybe it is time to implement a asset_exists() api function ?
-try:
-    bp_exists = ue.get_asset('/Game/Kaiju/Slicer/slicer_AnimBP.slicer_AnimBP')
-    ue.delete_asset(bp_exists.get_path_name())
-except:
-    pass
+# find_asset() returns None if the asset does not exist
+anim_bp = ue.find_asset('/Game/Kaiju/Slicer/slicer_AnimBP.slicer_AnimBP')
+if anim_bp:    
+    ue.delete_asset(anim_bp.get_path_name())
 
 anim_bp = anim_bp_factory.factory_create_new('/Game/Kaiju/Slicer/slicer_AnimBP')
 ```
 
-unfortunately, as you can see, we need a hack when creating new blueprints. Generating a Blueprint with the same name of another one will trigger a crash. We are investigating a better api to avoid that tricky exception.
+Always take into account that creating a Blueprint (of any kind)  with a name of an existing one, will trigger an error.
+If ue.find_asset() succeeds, we destroy the already existing asset. 
 
 Once the blueprint is created, we need to assign a custom event 'DoAttack' (triggered when the Kaiju is near a Pawn), anpther one called 'Boring' (triggered when the kaiju is stationary/idle for more than 10 seconds), 2 bool variables (Attack, Bored) and a float one (Speed):
 
@@ -752,49 +755,51 @@ Now it is time to create The Character Blueprint at which we will attach the pre
 ```python
 from unreal_engine.classes import Character
 
+# always check for already existing blueprints
+slicer_bp = ue.find_asset('/Game/Kaiju/Slicer/slicer_Blueprint.slicer_Blueprint')
+if slicer_bp:
+    ue.delete_asset(slicer_bp.get_path_name())
+    
 slicer_bp = ue.create_blueprint(Character, '/Game/Kaiju/Slicer/slicer_Blueprint')
 ```
 
+time to assign values:
+
 ```python
+
+# configure the capsule
 slicer_bp.GeneratedClass.get_cdo().CapsuleComponent.CapsuleHalfHeight = 150
 slicer_bp.GeneratedClass.get_cdo().CapsuleComponent.CapsuleRadius = 60
+
+# assign the the skeletal mesh and fix its relative position
 slicer_bp.GeneratedClass.get_cdo().Mesh.SkeletalMesh = slicer_mesh
 slicer_bp.GeneratedClass.get_cdo().Mesh.RelativeLocation = FVector(10, -3, -144)
-```
 
-TODO: assign the skeletal mesh, fix the capsule, assign the anim blueprint
+# assign the animation blueprint
+slicer_bp.GeneratedClass.get_cdo().Mesh.AnimClass = anim_bp.GeneratedClass
+```
 
-Filling the Event Graph
--
+the get_cdo() method returns the 'Class Default Object', it is a special instance of a class defining the default properties and components that following instances should inherit. When you edit a blueprint class you can effectively editing its 'cdo'.
 
-TODO: implement the idle timer triggering the bored state
-
-The BlackBoard
--
+We can now complete the first part of the tutorial by compiling the blueprint:
 
 ```python
-from unreal_engine.classes import BlackBoardDataFactory
-from unreal_engine.classes import BlackboardKeyType_Bool, BlackboardKeyType_String
-
-from unreal_engine.structs import BlackboardEntry
-
+ue.compile_blueprint(slicer_bp)
+slicer_bp.save_package()
 ```
-
-The Behavior Tree Graph
--
-
-TODO: Implement a decorator checking for pawn in a sphere, create a bt with a sequence of 'move to', 'raise event (attack)', 'wait'
-
-The Kaiju Brain
+Final notes
 -
 
-TODO: assign the bt to the AIController of the Kaiju
+You can get the whole script here: https://github.com/20tab/UnrealEnginePython/blob/master/tutorials/YourFirstAutomatedPipeline_Assets/kaiju_slicer_pipeline.py
 
-Testing it
--
+You can now drag and drop the blueprint in your scene or subclass it.
 
-TODO: write a unit test instantiating the Kaiju with a dumb pawn and checking for pawn in its virtual sphere.
+You can eventually spawn it directly from python:
 
-Final notes
--
+```python
+# get a reference to the editor world
+world = ue.get_editor_world()
+world.actor_spawn(slicer_bp.GeneratedClass, FVector(17, 22, 30))
+```
 
+In part2 we will see how to give a 'brain' to our Kaiju.