WEBVTT 00:00:00.960 --> 00:00:03.240 Hello and welcome to Scripting for Artists. My name is Sybren. 00:00:03.240 --> 00:00:05.960 In this episode, we'll be looking at 00:00:05.960 --> 00:00:09.000 creating your own Addon. In the previous video, we took our existing code 00:00:09.000 --> 00:00:11.960 to create a monkey grid, added some stuff around it 00:00:11.960 --> 00:00:14.120 to turn it into an operator. In this video, we'll do basically the same. 00:00:14.120 --> 00:00:17.840 We take our existing operator, 00:00:17.840 --> 00:00:20.600 add code around it, save it to a different place, and then, 00:00:20.600 --> 00:00:24.000 we'll have our Addon. Up to now, our code as always been 00:00:24.000 --> 00:00:27.240 inside the Blend file itself. And this is perfect for a situation 00:00:27.240 --> 00:00:30.720 where it is specific to that Blend file. It was one each wanted 00:00:30.720 --> 00:00:34.120 to scratch that. However, this is not always useful. 00:00:34.120 --> 00:00:37.080 Because maybe you want to use it in different Blend files as well. 00:00:37.080 --> 00:00:39.480 You always want to have it available to you. And maybe 00:00:39.480 --> 00:00:43.240 you even want to share your code with colleagues or with friends. 00:00:43.240 --> 00:00:45.840 In all these cases, turning your code into an Addon 00:00:45.840 --> 00:00:48.480 is the right choice. In this video, we'll look at the following. 00:00:48.480 --> 00:00:51.960 Will look at what is actually a code file, how do you edit it. 00:00:51.960 --> 00:00:55.080 We'll look at ingredients of an Addon. 00:00:55.080 --> 00:00:58.840 We'll turn our monkey grid operator into a monkey grid addon. 00:00:58.840 --> 00:01:01.360 Finally, we'll be looking at something you will be doing a lot, 00:01:01.360 --> 00:01:05.240 which is reloading your code after editing it. So let's get started. 00:01:05.240 --> 00:01:08.720 What is a code file actually? You may have guessed it, 00:01:08.720 --> 00:01:11.960 it's actually just a plain text file with a name 00:01:11.960 --> 00:01:16.360 that ends in ".py". There really is nothing more to it. 00:01:16.360 --> 00:01:18.840 Editing the code is also simple. You can pretty much use 00:01:18.840 --> 00:01:22.120 any Text Editor out there. I just don't use a word processor 00:01:22.120 --> 00:01:25.480 like Open Office or Microsoft Word, because those are not 00:01:25.480 --> 00:01:29.120 for just plain text. You may be tempted to use 00:01:29.120 --> 00:01:32.600 Blender's own internal Text Editor for it. After all, it even has 00:01:32.600 --> 00:01:35.360 syntax highlighting for Python. That means that, it has some 00:01:35.360 --> 00:01:38.600 basic knowledge of Python. It knows the key words like "for" and "if" 00:01:38.600 --> 00:01:41.960 and "depth", and it can color them differently, making it easier for you 00:01:41.960 --> 00:01:45.480 to understand the structure of the code. 00:01:45.480 --> 00:01:48.600 But with Blender's Editor, I always get confused. I never know whether 00:01:48.600 --> 00:01:52.080 I'm editing a text file that is part of Blender, 00:01:52.080 --> 00:01:55.720 or that's externally safe to disk. To save the file, you have to press Alt S 00:01:55.720 --> 00:01:58.720 and not Ctrl S, otherwise you save the Blend file 00:01:58.720 --> 00:02:01.960 instead of the Text file. I would rather recommend something different, 00:02:01.960 --> 00:02:04.120 something more suitable for the task. 00:02:04.120 --> 00:02:07.240 My personal favorite is Visual Studio code. It's an open source project 00:02:07.240 --> 00:02:10.600 by Microsoft and is a really nice editor. 00:02:10.600 --> 00:02:14.000 Other popular choices are @More Sublime Text. Or if you want 00:02:14.000 --> 00:02:17.080 to go really big, Pie Charm, there's lots of choice out there. 00:02:17.080 --> 00:02:19.960 So I recommend just download a few, give them all the tries, 00:02:19.960 --> 00:02:23.000 it would be the best. As for the name of the code file, 00:02:23.000 --> 00:02:25.600 I already mentioned that it has to end in that "py". 00:02:25.600 --> 00:02:28.360 There are few more requirements though. 00:02:28.360 --> 00:02:31.000 You don't have to know all of them. If you just stick to letters 00:02:31.000 --> 00:02:34.720 without any accents, underscores, and numbers, you'll be fine. 00:02:34.720 --> 00:02:37.120 If you want to know more about creating Addons, you can go 00:02:37.120 --> 00:02:40.600 to Help menu, then go to Advanced, Scripting, 00:02:40.600 --> 00:02:44.000 and Extending Blender, there's a lot of info there including an Addon tutorial. 00:02:44.000 --> 00:02:47.960 Now, let's look at the ingredients of an Addon. 00:02:47.960 --> 00:02:51.120 There are three things that you really have to have 00:02:51.120 --> 00:02:54.080 in your Addon. At the top of the file, there should be some metadata 00:02:54.080 --> 00:02:57.960 in a "bl" info date, and this metadata should include 00:02:57.960 --> 00:03:00.360 the name of the Addon, which version of Blender 00:03:00.360 --> 00:03:03.720 is compatible with it, the category the Addon should be in, 00:03:03.720 --> 00:03:06.720 and some other info. The second and third thing you need to have, 00:03:06.720 --> 00:03:09.600 you've already seen, and that's, the Register and Unregister functions. 00:03:09.600 --> 00:03:12.080 These functions tell Blender what your Addon contains 00:03:12.080 --> 00:03:15.720 so that it can be loaded and unloaded properly. 00:03:15.720 --> 00:03:18.960 The "bl" info you see at the top is called a dictionary. 00:03:18.960 --> 00:03:21.840 This is basically a lookup table. We've seen it before 00:03:21.840 --> 00:03:25.080 in Chapter 5 of Scripting for Artists. Okay, let's get 00:03:25.080 --> 00:03:28.480 this miniature addon to work. First, we have to save it to a location on disk. 00:03:28.480 --> 00:03:31.840 Does not really matter where right now 00:03:31.840 --> 00:03:34.480 because we will install it, and then Blender will copy it 00:03:34.480 --> 00:03:38.360 into the final location, and we can edit it from there later. 00:03:38.360 --> 00:03:40.360 So I'm going to save it to my Scripting for Artists folder, 00:03:40.360 --> 00:03:43.960 and I'm using only lowercase letters and underscores for the name, 00:03:43.960 --> 00:03:45.840 ending the naming ".py". 00:03:47.720 --> 00:03:51.240 Now we have to install the Addon. Go to User Preferences, 00:03:51.240 --> 00:03:56.840 go to Addons, install and find our smallest addon. 00:03:56.840 --> 00:03:59.480 Now the addon is installed, Blender copied for us to the right location. 00:03:59.480 --> 00:04:03.600 You can see, we're here. So it is my home directory 00:04:03.600 --> 00:04:06.000 ".config/blender/the version of Blender/script/addons/smallest_addon.py" 00:04:10.120 --> 00:04:13.080 we could have manually put it there, that's all fine. 00:04:13.080 --> 00:04:16.480 As long as the file is there, is good. But this way, Blender tells you 00:04:16.480 --> 00:04:19.840 where it has to go. You can see that, the User Interface shows 00:04:19.840 --> 00:04:22.960 very little information about our Addon. 00:04:22.960 --> 00:04:26.360 So before we even enable our Addon, let's see if we can fix that. 00:04:26.360 --> 00:04:30.360 We could go back to the Blender Text Editor, change the file, save it again, 00:04:30.360 --> 00:04:34.120 install it again, overwriting the file we just installed, and then, 00:04:34.120 --> 00:04:37.120 click Refresh. But I think that's too much work. 00:04:37.120 --> 00:04:40.360 Let's just take this file you see here and open that in a Code Editor instead. 00:04:40.360 --> 00:04:43.480 Here's a little trick for you. If you want to figure out 00:04:43.480 --> 00:04:47.240 where a Python file is, you can import it. 00:04:47.240 --> 00:04:50.840 You can say, "import smallest addon", and this loads our Addons. 00:04:50.840 --> 00:04:53.840 You can see that, because we have a Register function, 00:04:53.840 --> 00:04:57.080 for example, that prints "hello world", 00:04:57.080 --> 00:04:59.840 and we have an Unregistered function that says "goodbye world", 00:04:59.840 --> 00:05:02.960 as we expected, this gives you access from Blender to your Addons. 00:05:02.960 --> 00:05:05.600 And their secret names there, that doesn't should show up. 00:05:05.600 --> 00:05:09.360 "_file _" 00:05:09.360 --> 00:05:12.000 that will give you the file that the Addon is stored in. 00:05:12.000 --> 00:05:15.960 So this can copy paste into your editor and it actually opens the file. 00:05:15.960 --> 00:05:19.360 Here we are in Visual Studio code, let's open a file, 00:05:19.360 --> 00:05:22.960 and, of course, the file open dialog is very platform-specific. 00:05:22.960 --> 00:05:25.960 In my case, I can just paste the file name with control V, press "enter", 00:05:25.960 --> 00:05:29.080 then I open the file. And here, we see the code 00:05:29.080 --> 00:05:32.360 that Blender just installed for us. It is our code file. 00:05:32.360 --> 00:05:36.080 Now, let's extend that bl info dict with some more information. 00:05:36.080 --> 00:05:37.600 First, let's add an "author" field. 00:05:39.720 --> 00:05:42.600 You can add an email address if you want. That way, 00:05:42.600 --> 00:05:46.360 people can easily reach you. The rest of the fields are documented 00:05:46.360 --> 00:05:49.840 in the Python API manual. So in Blender, just go to Help, Python API, 00:05:49.840 --> 00:05:52.960 and then search for BL Info. Here are some more of the fields 00:05:52.960 --> 00:05:56.720 I just copied from that documentation. 00:05:56.720 --> 00:05:59.840 Location is the location of your Addon where people can find it in Blender itself. 00:05:59.840 --> 00:06:04.600 Since we won't have any User Interface yet, 00:06:04.600 --> 00:06:07.080 we can just type Operator Search here, and then people will have 00:06:07.080 --> 00:06:10.080 to find for themselves. Description just describes 00:06:10.080 --> 00:06:13.720 the functionality of your Addon, "more monkeys". The other fields, 00:06:13.720 --> 00:06:17.840 we'll leave empty for now. I've saved it with Ctrl S. 00:06:17.840 --> 00:06:20.600 Back at the User Preferences in Blender, we have changed the file on disk. 00:06:20.600 --> 00:06:23.360 Let's click the Refresh button. You can see that 00:06:23.360 --> 00:06:26.360 it collapsed this panel again, which is an indication that was reloaded. 00:06:26.360 --> 00:06:29.720 And when we open it, we get the info we typed there. 00:06:29.720 --> 00:06:33.240 Register and Unregister functions don't do much, 00:06:33.240 --> 00:06:36.360 they just print something to the screen. 00:06:36.360 --> 00:06:39.360 So, let's see what happens. I show the terminal here, 00:06:39.360 --> 00:06:42.240 when we enable the Addon, you can see "Hello World". Of course, 00:06:42.240 --> 00:06:45.600 when we disabled, you can see "Goodbye World". This just keeps going and going. 00:06:45.600 --> 00:06:48.360 Now, we know everything that's needed 00:06:48.360 --> 00:06:52.120 to turn our monkey grid operator into a monkey grid addon. 00:06:52.120 --> 00:06:54.720 So we're back in Visual Studio code. And you can see that 00:06:54.720 --> 00:06:57.360 I've opened the Addons directory on the side, so you can see, 00:06:57.360 --> 00:07:00.120 I've Blender Cloud Addon installed, and our smallest addon 00:07:00.120 --> 00:07:02.960 we just made. Let's make a new one. 00:07:02.960 --> 00:07:06.600 Create a new file called "monkey grid.py". From my smallest addon, 00:07:06.600 --> 00:07:12.000 I copy the BL info into it. Change the name to "Monkey Grid" 00:07:12.000 --> 00:07:14.480 because it's not a monkey grid addon. Let's go to Add New Meshes. 00:07:14.480 --> 00:07:17.480 So let's change the category to Mesh. Location is still "Operator Search", 00:07:17.480 --> 00:07:20.600 the description is now even more applicable than ever. 00:07:20.600 --> 00:07:24.120 Let's keep it all like it is now. 00:07:24.120 --> 00:07:27.600 Next to what we had, this is the only thing we need. 00:07:27.600 --> 00:07:31.480 We've a Code File that's in the right location, that has right name, 00:07:31.480 --> 00:07:35.000 that has the right BL info at the top. And now, all we need to do is, 00:07:35.000 --> 00:07:38.360 copy all the code we already had in that Blend file into this file. 00:07:38.360 --> 00:07:40.360 So back at Blender. 00:07:41.360 --> 00:07:45.960 I copy all the code. And the Visual Studio code, I paste it in. 00:07:48.600 --> 00:07:51.960 Just a quick check that there is nothing weird. 00:07:51.960 --> 00:07:54.720 This, we can remove, because we're no longer running it from the Editor itself, 00:07:54.720 --> 00:07:58.120 but only loading it as an Addon. We no longer need 00:07:58.120 --> 00:08:01.840 that little bit of magic. Save the file and now we'll go back to Blender. 00:08:01.840 --> 00:08:05.240 Let's start with a new file, just to be sure. 00:08:05.240 --> 00:08:09.960 Then, go to the User Preferences, again Refresh the list, 00:08:09.960 --> 00:08:10.600 search for monkey. 00:08:12.240 --> 00:08:15.080 And there, we have our monkey grid, we can enable it. 00:08:15.080 --> 00:08:17.480 Let's see if it works. Press F3, "monkey grid", 00:08:18.840 --> 00:08:23.840 and there we are, our own addon is working. 00:08:23.840 --> 00:08:27.120 It's nice that things are working. But things never are perfect in the first run. 00:08:27.120 --> 00:08:31.120 So what you will do is, often go back and forth 00:08:31.120 --> 00:08:33.960 between your Code Editor and Blender itself, and then 00:08:33.960 --> 00:08:37.120 you have to tell Blender to reload your scripts. 00:08:37.120 --> 00:08:40.240 We've already seen this Refresh button in the Addons list. 00:08:40.240 --> 00:08:43.960 But that only refreshes the Addons list, it does not actually reload 00:08:43.960 --> 00:08:47.000 your addon from disk once it's loaded. 00:08:47.000 --> 00:08:50.840 Let's make a change so that we can see that reloading actually did something. 00:08:50.840 --> 00:08:54.080 Back in the Code Editor. Let's say we change 00:08:54.080 --> 00:08:59.360 the default value of count Y, change it from 2 to 5, 00:08:59.360 --> 00:09:02.480 and save the file. Back in Blender, of course, if we redo the monkey grid, 00:09:02.480 --> 00:09:05.240 we still see 2 as the default value. 00:09:05.240 --> 00:09:09.960 Because we haven't reloaded the script yet. Press F3, Reload Script, 00:09:09.960 --> 00:09:13.120 that will actually reload your script. And now, when we do 00:09:13.120 --> 00:09:16.960 monkey grid, you can see that the default has been set to 5. 00:09:16.960 --> 00:09:20.080 So this is something you will do a lot. So that is it 00:09:20.080 --> 00:09:23.120 for this episode of Scripting for Artists. To recap, an Addon is 00:09:23.120 --> 00:09:25.960 just a text file that has a specific name in a certain location 00:09:25.960 --> 00:09:29.000 on your computer. It has meta data at the top 00:09:29.000 --> 00:09:32.120 in a BL info dictionary. It has a Registered and Unregistered functions 00:09:32.120 --> 00:09:35.000 at the bottom. And finally, reloading was done 00:09:35.000 --> 00:09:38.240 with that Reload Script Operator. So this is it. 00:09:38.240 --> 00:09:40.840 If you have any questions or remarks, please Leave a comment below. 00:09:40.840 --> 00:09:41.720 I will see you soon.