Access the set of Python scripts and Unreal Engine and Unity demo templates mentioned in the video here.
Full Video Transcript
Hi there. This is Ryan with Perforce Software. And today, I'd like to talk about the P4 template tool. And what this is is a free to use tool that we're hosting on our GitHub that you can download and use at your leisure.
The intention for this tool is to help folks get a leg up when starting out Helix Core projects and building things into their Helix Core server. And particularly if you're in a studio environment where perhaps you're creating very similar projects repeatedly. So whether it's for individual users that you'd like to duplicate a certain Unreal project template into separate projects that are gonna go forward. Or perhaps you're working on something like commercial advertisements where it's a very quick turnaround and you have a set based project that when these new projects come in, you just wanna quickly duplicate and get to work.
So that's really what this tool is designed to help alleviate and make things easier for your admins when deploying new projects out. So let's get into it. So over on the left here, I just have the link up to our public GitHub page here. So it's github.com/perforce/p4templates.
And here's where you'll find the code that's being used, which is primarily Python with a little bit of IQT mixed in there for the UI.
As well, you'll find our code of conduct, our licensing, and the read me, obviously, with lists of requirements that you would need to run this tool, which really comes down to Python 3, the P4 Python API that we offer, as well as PyQT.
It'll also go over various server configuration files and how the templates work as well as CLI usage and that sort of thing.
So definitely check that out because, I mean, if you're watching this video, you're probably already at the point where you're gonna download this tool. So with that, the tool itself as mentioned is built out in Python and you can just run the raw Python if you'd like.
Also included here is the batch script to build a Windows executable. So that way you can use P4 installer to wrap everything up into a simple exe. If you're looking to deploy this on each individual machine or just have it a little more controlled for your end users.
So whether you're using the Python entry point, which is the Python entry point, which is our P4 template tool Python file here, Or if you're using the EXE, you're still gonna have the option for the same arguments to be passed in, which I'll show you what those look like. So if I were to run the exe with our help flag, we're going to have the option to pass in a path to our configuration file, as well as our template directory or where it's going to fetch these JSON template files.
So those are the two arguments you can pass in. That template directory file, you can also define within your config file.
So if I step over here, you can actually find that right here.
As well as if you don't define either of these, the tool itself is going to look right next to itself for these files. So if you have a template directory just sitting next to this EXE, you'll use that to scrape and load up your templates.
And if you have a config in that spot, it will use that for connecting to your server.
If you don't have a config in place and run the tool, it will still open. It'll let you author templates and all of that, but you won't be able to run it because it doesn't know what server to enact these changes on.
Taking a quick look at the config file, it's pretty simple. You just need to tell it what Helix Core server you're connecting to, the username it's going to be using to execute these commands.
And if you need to, you can also put a password in here or your ticket value. If you don't fill this out and leave it at null, it will first attempt to use any local tickets that you may have on your system.
So if you've already logged in, it can always reference that and you don't have to put it here in plain text.
As well as your character set, if you're connecting to a Unicode server. And as mentioned, you can also define a template directory.
So if you have a server location where you're storing all your templates and you want them to load from there, you can define that in your config.
So that way you just have to have your config file next to the EXE or passed in as an argument.
The templates themselves, if we take a look at them, they are just JSON files.
And in here, you can define out any number of depots you'd like to create, as well as groups, users, streams, protections, types, branching. So if you need to duplicate existing Depot files into your new project, you can do that as well with this tool in a P4 populate style.
And in here, you can also see, we do have this variable syntax built into the templates. So what that will allow you to do is anytime you need to carve out spaces for reuse in these variables, you just enter them in curly brace syntax here.
And when you load up that template, the tool will notice all of those variables and there'll be offered to you to fill out in how to deploy your new project and fill those variables in at time of run.
So as mentioned, we can define our depots. We can define our full groups, including group users. If you'd like, you can fill those out. If you typically have a set of users that are involved in every project, you can have them automatically added here. You can create new users, create streams as well as define stream hierarchies. So you'll be able to make a main line development branches off of those release streams, anything you kind of need. You can define that out here.
And then with the protections and the types, you can also add those here. So the protection values, if you're looking to define out separate read groups versus rewrite groups for permissions on your project, you can define those. They will be prepended to your permissions table. So I'm not going to append those at the end because that's typically where your super user definitions and your admin user definitions are.
So this will prepend it to the top of the list. So that might be one thing you will have to do is go and reorder that into the correct position for your protections table if you have a preferred organization to it. With both the protections and the type map entries, these are meant to be add only. And what I mean by that is if that line already exists in the protections table, it won't add that line again. It should skip over it as well as the types. If the types are already defined, it will only be adding to your type map. It's not going to clear anything out or delete, because I don't want to be destructive in this process.
Since the type map is particularly a server wide setting, any edits there can be very important.
So as mentioned, these are just JSON files.
So if you end up having another tool that you'd like to use to write these out or write them by hand, you're free to come in here and edit them so long as it's a valid JSON.
However, we do also have, and if I jump back here and run the tool and load this up, we do also have the ability to edit them within the UI.
So with our P4 project template tool here, the first screen when you load it is going to be your loader and runner screen. And so also down here in our output, we can see that it found the template folder and it went through and found all of our files within there and loaded those into our single select dropdown here.
So for this example, I'll grab this default Unreal template.
And again, any of those variables that were defined in the template template with curly braces are now being lifted to our list here. And until I fill out a value for all of these variables, I will not be able to run this template and actually build anything out.
So I could come in here and go demo temp, and then now I'm able to run. So this is how you're going to be able to run and deploy your templates from this view.
If we needed to make changes to a template, or if we wanted to author a new one, we could always come in here and say, edit this template, which will open up the editor view.
In the editor view, anytime we need to add or remove something, typically we've got our buttons down here, so I can go ahead and add a new depot.
And let's say we'll just call this one a new variable depot, and we can add that in place. So that way later, that will present on that main loader screen for use. And then I can also remove this if need be. So I can add a user if someone is going to be a particular owner of this depot, change its type, change its name.
Or if it's a stream, you can also change your stream depth if need be. Going down the line, we can then take a look at our streams.
And in this view, again, we can add as many streams as we like. We can edit our basic properties for our streams, including our options.
If we can change our type, if this was a development stream, we can then define a parent, the associated with that. If we take a look at our development stream here. And you'll also notice here that my development stream is referencing those same, variables that have been written everywhere else. So this project depot hasn't been built yet. Project dev is its own name and its parent is actually that project main, which hasn't been built out yet. So you can put those in, reference them, chain them together. If you have a preferred flow where let's say you have a main line and then an approval or integration branch underneath with a development branch underneath, And perhaps you have other virtual streams you'd like to build out for various read capabilities.
We can also define out our advanced settings here. So if I have particular ignores that I'm looking to include into my stream spec, that can be defined.
If I have files that need to be remapped, I can, as well as if there are specific paths that I would like to put in place. Anywhere where you see this style of list, we could always come in here and enter a value.
And then as soon as you enter a value, it's always going to add one more blank line at the end for you to enter any new data. So you can always come through here, write new lines, and every time you add them, it'll add that in place.
And this kind of UI language is carried throughout the pool. Stepping to groups, we can fill everything out here that we need to.
If you have owners or users or subgroups, those are just gonna be comma separated, lists effectively written out as a string to be put in place. If we need to make any users, we can come in here and define that.
Anything that's blank will attempt to use a default value that's defined within the Python code. Or you can always just fill those out explicitly here as well.
Our protections table. So this one again is granting right access to that group we're going to create, and it's gonna point it to that depot path. So that way you can perform very atomic and permissions assignment to keep your server safe and define it out once and then reuse that template over and over again to have them all built out in a very similar fashion.
If we step to our type maps, we've got this kind of separated out in more of a dictionary style where we've got our various types to the side, and then you can always, again, add new types to each or add new file paths to each type.
If we need to go ahead and make a new type, we can do that and then let that go.
And then we've got our new type name to add in. If I need to rename this, we can go ahead and, and do that.
Or if we just need to remove it, we can always delete that.
And then the one thing that I won't be showing explicitly here today, but for, again, for branching or populating off of existing data in your Helix Core server, we can always come in here and make a new branch.
These typically with this tool, it will create the branch, then use it to populate the data and then delete the branch. So it's going to be very short lived data as far as a branch goes.
But within here, down at the bottom, we can then define out our, essentially, our existing path to whatever data we're looking to copy. And then again, I would be able to come in here and say, you know, project depot.
If I were looking for essentially a very simple valve branch where I'm saying take everything from this existing depot and duplicate it into my project depot and continue on from there, You can build this this out so that way your projects come pre-populated with data right from the get go.
This also allows you to rename files.
So if you add an existing project, let's say an Unreal project file, You could also rename that to the new project if you need to.
So with that, if we have this template built out as we prefer, we can always come in here and hit save. And if we want it to save over that same unreal one, we could, or we could also give it a new name and then save this as a new file.
So with that, I'm gonna go ahead and take a view here of our Unreal new.
And so we've got all our values here. So that looks like I deleted that one. Boom. If we were to take a peek down here at our branches, we've got our new data saved here. Once done editing, I can go ahead and close this down and then I can again, go back and reselect my unreal template.
And so I can fill this out and I can hit run. And then down here in our output, you can see that right here, it's telling me it's connecting to our server.
I haven't provided a password, so it used my local ticket. The connection was made.
It began processing the template. It found no changes in the time map. It saved our protections table. It created our new user.
It created our new depot, our new group, as well as our two streams, and then it was finished. So very quick to deploy all those pieces out.
And if this template were larger, it would deploy all that out as well.
From here, I can go ahead and let's step over to our Helix admin tool.
And I can go ahead and take a peek in here that here we've got our new user that was created, Our permissions table has our new permission line in place. So I could go ahead and move this around because typically I'd want it underneath this no access level.
I can then save that.
Our new depot exists.
And if we step over to P4V, we now have our depot and our two streams that are in place. So everything built out just how we like, and this would be infinitely repeatable without needing to edit that template again.
You would just be able to jump back in, use that template, and deploy out a new project, hopefully within seconds. So that way you and your team are ready to go with the protections and kind of workflow parameters that you like in place without worry.
One other thing I'd like to talk about is the command line interface. And if you're not looking to use the UI too often and instead you want to just put this command in a into a batch with other things that you may have going on for project creation, you can do that as well.
So to actually do that one, though, we go into P4 templates, we'll go into kernel and it's going to be this process template file here that you're going to want to run.
So with that, if I were to go Python process template -h, you can see here that we do have in this help section a bit about our usage. So this is going to be if you want if you already know the template you want to use and whether it's name or location, you can pass this in and run this directly.
So you would define out your configuration, any parameters that you would need to define, which you define those as a dictionary effectively.
So if we go in here and talk to CLI usage, you can see that if we had a parameter, we would just go ahead and do dash p for our parameters field and then enter in the variable, colon, your substitution, and you can do that for any number of parameters.
If you attempt to run a template and you haven't provided it the necessary parameters, it's going to fail out and tell you, hey, you you can't run this unless you give me all of the variable values that are needed.
So that's important if you are running this template and there are parameters in place that you will have to fill that out. You can also run this in dry run mode. So that way, it will just report out what it would do if you wanna check your templates before you're actually pushing everything out.
So if you're looking to run this as part of a larger build operation or batch script, you would use this process template entry point to run everything.
So with that, I hope this tool helps, and especially if you're often making projects in depots and having to do this all manually. Hopefully, this makes your life a little bit simple. Have a good one.